Add documentation for cost module

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

@@ -20,11 +20,46 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, cost_item=None, cost_rate=None):
+        """Assigns a cost value to a cost item from a schedule of rates
+
+        Instead of assigning cost values from scratch for each cost item in a
+        cost schedule, the cost values may instead be assigned from a schedule
+        of rates.
+
+        A schedule of rates is just another cost schedule which have cost values
+        but no quantities. This API will allow you to "copy" the values from a
+        cost item in the schedule of rates into another cost item in your own
+        cost schedule. When the schedule of rates value is updated, then your
+        cost item values will also be updated. You can think of the schedule of
+        rates as a "template" to quickly populate your rates from.
+
+        :param cost_item: The IfcCostItem that you want to copy the values to
+        :type cost_item: ifcopenshell.entity_instance.entity_instance
+        :param cost_rate: The IfcCostItem that you want to copy the values from
+        :type cost_rate: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            # Let's create a schedule of rates with a single rate in it of 5.0
+            rate_tables = ifcopenshell.api.run("cost.add_cost_schedule", model,
+                predefined_type="SCHEDULEOFRATES")
+            rate = ifcopenshell.api.run("cost.add_cost_item", model, cost_schedule=schedule)
+            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})
+
+            # And this schedule will be for our actual cost plan / estimate / etc
+            schedule = ifcopenshell.api.run("cost.add_cost_schedule", model)
+            item = ifcopenshell.api.run("cost.add_cost_item", model, cost_schedule=schedule)
+
+            # Now the cost item has the same rate as the one from the schedule of rate's item
+            ifcopenshell.api.run("cost.assign_cost_value", model, cost_item=item, cost_rate=rate)
+        """
         self.file = file
-        self.settings = {"cost_item": None, "cost_rate": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"cost_item": cost_item, "cost_rate": cost_rate}
 
     def execute(self):
         for cost_value in self.settings["cost_item"].CostValues: