Add API docs for drawing module

src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py

@@ -21,14 +21,46 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, relating_product=None, related_object=None):
+        """Associates a product and an object, typically for annotation
+
+        Warning: this is an experimental API.
+
+        When you want to draw attention to a feature or characteristic (such as
+        a dimension, material, or name) or of a product (e.g. wall, slab,
+        furniture, etc), an annotation object is created. This annotation is
+        then associated with the product so that it can reference attributes,
+        properties, and relationships.
+
+        For example, an annotation of a line will be associated with a grid
+        axis, such that when that grid axis moves, the annotation of that grid
+        axis (which is typically truncated to the extents of a drawing) will
+        also move.
+
+        Another example might be a label of a furniture product, which might
+        have some text of the name of the furniture to be shown on drawings or
+        in 3D.
+
+        :param relating_product: The IfcProduct the object is related to
+        :type relating_product: ifcopenshell.entity_instance.entity_instance
+        :param related_object: The object (typically IfcAnnotation) that the
+            product is related to
+        :type related_object: ifcopenshell.entity_instance.entity_instance
+        :return: The created IfcRelAssignsToProduct relationship
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            furniture = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture")
+            annotation = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcAnnotation")
+            ifcopenshell.api.run("drawing.assign_product", model,
+                relating_product=furniture, related_object=annotation)
+        """
         self.file = file
         self.settings = {
-            "relating_product": None,
-            "related_object": None,
+            "relating_product": relating_product,
+            "related_object": related_object,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         is_grid_axis = self.settings["relating_product"].is_a("IfcGridAxis")

src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py

@@ -18,11 +18,27 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, text_literal=None, attributes=None):
+        """Edits the attributes of an IfcTextLiteral
+
+        For more information about the attributes and data types of an
+        IfcTextLiteral, consult the IFC documentation.
+
+        :param reference: The IfcTextLiteral entity you want to edit
+        :type reference: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            text = model.createIfcTextLiteral()
+            ifcopenshell.api.run("drawing.edit_text_literal", model,
+                text_literal=text, attributes={"Literal": "MY ANNOTATION"})
+        """
         self.file = file
-        self.settings = {"text_literal": None, "attributes": {}}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"text_literal": text_literal, "attributes": attributes or {}}
 
     def execute(self):
         for name, value in self.settings["attributes"].items():

src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py

@@ -21,14 +21,38 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, relating_product=None, related_object=None):
+        """Unassigns a product and an object (typically an annotation)
+
+        Smart annotation objects can be associated with products so that they
+        can annotate attributes and properties. This function lets you remove
+        the association, so that you may change the assocation with another
+        object later or leave the annotation as a "dumb" annotation.
+
+        :param relating_product: The IfcProduct the object is related to
+        :type relating_product: ifcopenshell.entity_instance.entity_instance
+        :param related_object: The object (typically IfcAnnotation) that the
+            product is related to
+        :type related_object: ifcopenshell.entity_instance.entity_instance
+        :return: The created IfcRelAssignsToProduct relationship
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            furniture = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture")
+            annotation = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcAnnotation")
+            ifcopenshell.api.run("drawing.assign_product", model,
+                relating_product=furniture, related_object=annotation)
+
+            # Let's change our mind and remove the relationship
+            ifcopenshell.api.run("drawing.unassign_product", model,
+                relating_product=furniture, related_object=annotation)
+        """
         self.file = file
         self.settings = {
-            "relating_product": None,
-            "related_object": None,
+            "relating_product": relating_product,
+            "related_object": related_object,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for rel in self.settings["related_object"].HasAssignments or []: