Write documentation for the nest API module.

src/ifcopenshell-python/ifcopenshell/api/nest/assign_object.py

@@ -21,14 +21,76 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, related_object=None, relating_object=None):
+        """Assigns an object as a nested child to a parent host
+
+        All physical IFC model elements must be part of a hierarchical tree
+        called the "spatial decomposition", where large things are made up of
+        smaller things. This tree always begins at an "IfcProject" and is then
+        broken down using "decomposition" relationships, of which aggregation is
+        the first relationship you will use.
+
+        Another type of "decomposition" relationship is known as "nesting".
+        Nesting is used when an child object is physically attached to a parent
+        host object, through a physical predetermined connection point. The
+        child object must be specifically designed to attach to a other objects
+        at specific positions with a particular form factor. Examples include
+        faucets which must always be attached through a predrilled hole in a
+        basin. Alternatively, it could be a modular attachment with a
+        correlating male and female joint that must join at a particular point.
+        Because there is a strict connection point, when the parent moves, all
+        nested children must move with the parent. Another example might be a
+        predrilled hole in a door panel where hardware must fit through.
+
+        Nesting relationships are not very commonly used in most design and
+        construction models. Its main usecase is in modular construction, kit of
+        parts, or fabrication models.
+
+        As a product may only have a single locaion in the "spatial
+        decomposition" tree, assigning an nesting relationship will remove any
+        previous aggregation, containment, or nesting relationships it may have.
+
+        IFC placements follow a convention where the placement is relative to
+        its parent in the spatial hierarchy. If your product has a placement,
+        its placement will be recalculated to follow this convention.
+
+        For physical connections which are part of a distribution system, such
+        as a plug connecting into a GPO, or a duct connecting to an AHU, or two
+        pipe segments connecting with a bend, tee, or wye fitting, you should
+        not nest the two objects directly. Instead, you should nest a connection
+        port, which determines the type of compatible distribution flow that can
+        be connected to it. To do this, do not use this function, but instead
+        use the more specific functions in the ifcopenshell.api.system module.
+
+        Note that nesting relationships may also be used by non-physical
+        elements, such as cost items or tasks. In this context, nesting means
+        that there is an implied order to the child cost items or tasks (i.e.
+        task 1 should be shown before task 2). It is not necessary to use this
+        function for nesting non-physical elements. Instead, it is recommended
+        to instead just use the relevant API functions, like
+        ifcopenshell.api.cost.add_cost_item or
+        ifcopenshell.api.sequence.add_task.
+
+        :param related_object: The child of the nesting relationship, typically
+            an IfcElement.
+        :type related_object: ifcopenshell.entity_instance.entity_instance
+        :param relating_object: The host parent of the nesting relationship,
+            typically an IfcElement.
+        :type relating_object: ifcopenshell.entity_instance.entity_instance
+        :return: The IfcRelNests relationship instance
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Faucets are designed to attach onto a sink through a predrilled hole.
+            sink = ifcopenshell.api.run("root.create_entity", model,
+                ifc_class="IfcSanitaryTerminal", predefined_type="SINK")
+            faucet = ifcopenshell.api.run("root.create_entity", model,
+                ifc_class="IfcValve", predefined_type="FAUCET")
+            ifcopenshell.api.run("nest.assign_object", model, related_object=faucet, relating_object=sink)
+        """
         self.file = file
-        self.settings = {
-            "related_object": None,
-            "relating_object": None,
-        }
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"related_object": related_object, "relating_object": relating_object}
 
     def execute(self):
         nests = None