Add documentation for cost module

src/ifcopenshell-python/ifcopenshell/api/cost/assign_cost_item_quantity.py

@@ -20,11 +20,62 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, cost_item=None, products=None, prop_name=""):
+        """Adds a cost item quantity that is parametrically connected to a product
+
+        A cost item may have its subtotal calculated by multiplying a unit value
+        by a quantity associated with the cost item. That quantity may be either
+        manually specified or parametrically connected to a quantity on a
+        product. This API function lets you create that parametric connection.
+
+        For example, you may wish to have a cost item linked to the "NetVolume"
+        quantity on all IfcSlabs. Each quantity has a name which you can
+        specify. If the quantity is updated in-place (which should occur for
+        Native IFC applications) then the quantity for the cost item will
+        automatically update as well. If the quantity is deleted and then
+        re-added, then the parametric relationship is also lost.
+
+        This API also automatically assigns a control relationship between the
+        cost item and the product, so it is not necessary to use
+        ifcopenshell.api.control.assign_control.
+
+        :param cost_item: The IfcCostItem to assign parametric quantities to
+        :type cost_item: ifcopenshell.entity_instance.entity_instance
+        :param products: The IfcObjects to assign parametric quantities to
+        :type products: list[ifcopenshell.entity_instance.entity_instance]
+        :param prop_name: The name of the quantity. If this is not specified,
+            then it is assumed that there is no calculated quantity, and the
+            number of objects are counted instead.
+        :type prop_name: str, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            schedule = ifcopenshell.api.run("cost.add_cost_schedule", model)
+            item = ifcopenshell.api.run("cost.add_cost_item", model, cost_schedule=schedule)
+
+            # Let's imagine a unit cost of 5.0 per unit volume
+            value = ifcopenshell.api.run("cost.add_cost_value", model, parent=item)
+            ifcopenshell.api.run("cost.edit_cost_value", model, cost_value=value,
+                attributes={"AppliedValue": 5.0})
+
+            slab = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSlab")
+            # Usually the quantity would be automatically calculated via a
+            # graphical authoring application but let's assign a manual quantity
+            # for now.
+            qto = ifcopenshell.api.run("pset.add_qto", model, product=slab, name="Qto_SlabBaseQuantities")
+            ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"NetVolume": 42.0})
+
+            # Now let's parametrically link the slab's quantity to the cost
+            # item. If the slab is edited in the future and 42.0 changes, then
+            # the updated value will also automatically be applied to the cost
+            # item.
+            ifcopenshell.api.run("cost.assign_cost_item_quantity", model,
+                cost_item=item, products=[slab], prop_name="NetVolume")
+        """
         self.file = file
-        self.settings = {"cost_item": None, "products": [], "prop_name": ""}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"cost_item": cost_item, "products": products or [], "prop_name": prop_name}
 
     def execute(self):
         if self.settings["prop_name"]: