Write docs for profile API module

src/ifcopenshell-python/ifcopenshell/api/profile/add_arbitrary_profile.py

@@ -20,11 +20,35 @@ import ifcopenshell.util.unit
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, profile=None, name=None):
+        """Adds a new arbitrary polyline-based profile
+
+        The profile is represented as a polyline defined by a list of
+        coordinates. Only straight segments are allowed. Coordinates must be
+        provided in SI meters.
+
+        To represent a closed curve, the first and last coordinate must be
+        identical.
+
+        :param profile: A list of coordinates
+        :type profile: list[list[float]]
+        :param name: If the profile is semantically significant (i.e. to be
+            managed and reused by the user) then it must be named. Otherwise,
+            this may be left as none.
+        :type name: str, optional
+        :return: The newly created IfcArbitraryClosedProfileDef
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # A 10mm by 100mm rectangle, such that might be used as a wooden
+            # skirting board or kick plate.
+            square = ifcopenshell.api.run("profile.add_arbitrary_profile", model,
+                profile=[(0., 0.), (.01, 0.), (.01, .1), (0., .1), (0., 0.)],
+                name="SK01 Profile")
+        """
         self.file = file
-        self.settings = {"profile": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"profile": profile, "name": name}
 
     def execute(self):
         self.settings["unit_scale"] = ifcopenshell.util.unit.calculate_unit_scale(self.file)
@@ -33,7 +57,7 @@ class Usecase:
             curve = self.file.createIfcPolyline([self.file.createIfcCartesianPoint(p) for p in points])
         else:
             curve = self.file.createIfcIndexedPolyCurve(self.file.createIfcCartesianPointList3D(points))
-        return self.file.createIfcArbitraryClosedProfileDef("AREA", None, curve)
+        return self.file.createIfcArbitraryClosedProfileDef("AREA", self.settings["name"], curve)
 
     def convert_si_to_unit(self, co):
         if isinstance(co, (tuple, list)):

src/ifcopenshell-python/ifcopenshell/api/profile/add_parameterized_profile.py

@@ -18,11 +18,30 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, ifc_class=None):
+        """Adds a new parameterised profile
+
+        IFC offers parameterised profiles for common standardised hot roll
+        steel sections and common concrete forms. A full list is available on
+        the IFC documentation as subclasses of IfcParameterizedProfileDef.
+
+        Currently, this API has no benefit over directly calling
+        ifcopenshell.file.file.create_entity.
+
+        :param ifc_class: The subclass of IfcParameterizedProfileDef that you'd
+            like to create.
+        :type ifc_class: str
+        :return: The newly created element depending on the specified ifc_class.
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            circle = ifcopenshell.api.run("profile.add_parameterized_profile", model,
+                ifc_class="IfcCircleProfileDef")
+            circle.Radius = 1.
+        """
         self.file = file
-        self.settings = {"ifc_class": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"ifc_class": ifc_class}
 
     def execute(self):
         return self.file.create_entity(self.settings["ifc_class"])

src/ifcopenshell-python/ifcopenshell/api/profile/edit_profile.py

@@ -18,11 +18,30 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, profile=None, attributes=None):
+        """Edits the attributes of an IfcProfileDef
+
+        For more information about the attributes and data types of an
+        IfcProfileDef, consult the IFC documentation.
+
+        :param profile: The IfcProfileDef entity you want to edit
+        :type profile: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            circle = ifcopenshell.api.run("profile.add_parameterized_profile", model,
+                ifc_class="IfcCircleProfileDef")
+            circle = 1.
+
+            ifcopenshell.api.run("profile.edit_profile", model,
+                profile=circle, attributes={"ProfileName": "1000mm Dia"})
+        """
         self.file = file
-        self.settings = {"profile": None, "attributes": {}}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"profile": profile, "attributes": attributes or {}}
 
     def execute(self):
         for name, value in self.settings["attributes"].items():

src/ifcopenshell-python/ifcopenshell/api/profile/remove_profile.py

@@ -18,11 +18,23 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, profile=None):
+        """Removes a profile
+
+        :param profile: The IfcProfileDef to remove.
+        :type profile: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            circle = ifcopenshell.api.run("profile.add_parameterized_profile", model,
+                ifc_class="IfcCircleProfileDef")
+            circle = 1.
+            ifcopenshell.api.run("profile.remove_profile", model, profile=circle)
+        """
         self.file = file
-        self.settings = {"profile": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"profile": profile}
 
     def execute(self):
         self.file.remove(self.settings["profile"])