Add API documentation for the material module

src/ifcopenshell-python/ifcopenshell/api/material/add_constituent.py

@@ -18,11 +18,68 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, constituent_set=None, material=None):
+        """Adds a new constituent to a constituent set
+
+        A constituent describes how a portion of an object is made out of a
+        material whereas other portions of the object is made out of other
+        materials. For example, a window might be made out of an aluminium frame
+        and a glass panel. The aluminium used for the frame is one constituent
+        of the material, and glass would be another constituent. Another example
+        might be concrete, where one constituent might be cement, and another
+        constituent might be binder. In the case of the window, the constituent
+        is represented explicitly by the geometry of the window frame and the
+        geometry of the window panel. In the case of a concrete slab, the
+        constituents might be represented in terms of percentages.
+
+        Constituents are not available in IFC2X3.
+
+        :param constituent_set: The IfcMaterialConstituentSet that the
+            constituent is part of. The constituent set represents a group of
+            constituents. See ifcopenshell.api.material.add_material_set for
+            information on how to add a constituent set.
+        :type constituent_set: ifcopenshell.entity_instance.entity_instance
+        :param material: The IfcMaterial that the constituent is made out of.
+        :type material: ifcopenshell.entity_instance.entity_instance
+        :return: The newly created IfcMaterialConstituent
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Let's imagine we have a window type that has an aluminium frame
+            # and a glass glazing panel. Notice we are assigning to the type
+            # only, as all occurrences of that type will automatically inherit
+            # the material.
+            window_type = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWindowType")
+
+            # First, let's create a constituent set. This will later be assigned
+            # to our window element.
+            material_set = ifcopenshell.api.run("material.add_material_set", model,
+                name="Window", set_type="IfcMaterialConstituentSet")
+
+            # Let's create a few materials, it's important to also give them
+            # categories. This makes it easy for model recipients to do things
+            # like "show me everything made out of aluminium / concrete / steel
+            # / glass / etc". The IFC specification states a list of categories
+            # you can use.
+            aluminium = ifcopenshell.api.run("material.add_material", model, name="AL01", category="aluminium")
+            glass = ifcopenshell.api.run("material.add_material", model, name="GLZ01", category="glass")
+
+            # Now let's use those materials as two constituents in our set.
+            ifcopenshell.api.run("material.add_constituent", model,
+                constituent_set=material_set, material=aluminium)
+            ifcopenshell.api.run("material.add_constituent", model,
+                constituent_set=material_set, material=glass)
+
+            # Great! Let's assign our material set to our window type.
+            # We're technically not done here, we might want to add geometry to
+            # our window too, but to keep this example simple, geometry is
+            # optional and it is enough to say that this window is made out of
+            # aluminium and glass.
+            ifcopenshell.api.run("material.assign_material", model, product=window_type, material=material_set)
+        """
         self.file = file
-        self.settings = {"constituent_set": None, "material": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"constituent_set": constituent_set, "material": material}
 
     def execute(self):
         constituents = list(self.settings["constituent_set"].MaterialConstituents or [])