From 22eb0bf2e47c1577453ea52e921eac95b5117e50 Mon Sep 17 00:00:00 2001
From: Dion Moult <dion@thinkmoult.com>
Date: Wed, 16 Nov 2022 18:38:51 +0900
Subject: [PATCH] Write API documentation for control module

---
 .../api/control/assign_control.py             | 50 +++++++++++++++++--
 .../api/control/unassign_control.py           | 34 +++++++++++--
 2 files changed, 74 insertions(+), 10 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py b/src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py
index 2a5ce12754..e3c4b554b1 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py
@@ -21,14 +21,54 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, relating_control=None, related_object=None):
+        """Assigns a planning control or constraint to an object
+
+        IFC can describe concepts that control other objects. For example, a
+        planning calendar controls the availability of working days for
+        construction planning. As another example, a cost item might constrain
+        or limit the ability to procure and build a product.
+
+        This usecase lets you assign controls following the rules of the IFC
+        specification. This is an advanced topic and assumes knowledge of the
+        IFC concepts to determine what is allowed to control what. In the
+        future, this API will likely be deprecated in favour of multiple usecase
+        specific APIs.
+
+        :param relating_control: The IfcControl entity that is creating the
+            control or constraint
+        :type relating_control: ifcopenshell.entity_instance.entity_instance
+        :param related_object: The IfcObjectDefinition that is being controlled
+        :type related_object: ifcopenshell.entity_instance.entity_instance
+        :return: The newly created IfcRelAssignsToControl
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # One common usecase is to assign a calendar to a task
+            calendar = ifcopenshell.api.run("sequence.add_work_calendar", model)
+            schedule = ifcopenshell.api.run("sequence.add_work_schedule", model)
+            task = ifcopenshell.api.run("sequence.add_task", model,
+                work_schedule=schedule)
+
+            # All subtasks will inherit this calendar, so assigning a single
+            # calendar to the root task effectively defines a "default" calendar
+            ifcopenshell.api.run("control.assign_control", model,
+                relating_control=calendar, related_object=task)
+
+            # Another common example might be relating a cost item and a product
+            wall = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")
+            schedule = ifcopenshell.api.run("cost.add_cost_schedule", model)
+            cost_item = ifcopenshell.api.run("cost.add_cost_item", model,
+                cost_schedule=schedule)
+            ifcopenshell.api.run("control.assign_control", model,
+                relating_control=cost_item, related_object=wall)
+        """
         self.file = file
         self.settings = {
-            "relating_control": None,
-            "related_object": None,
+            "relating_control": relating_control,
+            "related_object": related_object,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if self.settings["related_object"].HasAssignments:
diff --git a/src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py b/src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py
index 9783bfba83..9b5a786311 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py
@@ -21,14 +21,38 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, relating_control=None, related_object=None):
+        """Unassigns a planning control or constraint to an object
+
+        :param relating_control: The IfcControl entity that is creating the
+            control or constraint
+        :type relating_control: ifcopenshell.entity_instance.entity_instance
+        :param related_object: The IfcObjectDefinition that is being controlled
+        :type related_object: ifcopenshell.entity_instance.entity_instance
+        :return: If the control still is related to other objects, the
+            IfcRelAssignsToControl is returned, otherwise None.
+        :rtype: ifcopenshell.entity_instance.entity_instance, None
+
+        Example::
+
+            # Let's relate a cost item and a product
+            wall = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")
+            schedule = ifcopenshell.api.run("cost.add_cost_schedule", model)
+            cost_item = ifcopenshell.api.run("cost.add_cost_item", model,
+                cost_schedule=schedule)
+            ifcopenshell.api.run("control.assign_control", model,
+                relating_control=cost_item, related_object=wall)
+
+            # And now let's change our mind
+            ifcopenshell.api.run("control.unassign_control", model,
+                relating_control=cost_item, related_object=wall)
+        """
+
         self.file = file
         self.settings = {
-            "relating_control": None,
-            "related_object": None,
+            "relating_control": relating_control,
+            "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 []: