Add API documentation for the material module

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

@@ -21,9 +21,46 @@ import ifcopenshell.util.element
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, material=None, element=None):
+        """Copies a material to an element
+
+        This convenience function exists to allow you to easily unassign any
+        existing material an element has, and assign a new material to it.
+        Essentially, it is a form a copy / pasting a material from one element
+        to another.
+
+        It's a bit out of place, and will likely be redesigned or removed in the
+        future.  It's not recommended to use this function, and
+        ifcopenshell.api.material.assign_material should be used instead.
+
+        :param material: The IfcMaterial to assign to the element.
+        :type material: ifcopenshell.entity_instance.entity_instance
+        :param element: The IfcElement or IfcElementType to remove all previous
+            materials from and assign the new material to.
+        :type element: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            concrete = ifcopenshell.api.run("material.add_material", model, name="CON01", category="concrete")
+            wood = ifcopenshell.api.run("material.add_material", model, name="TIM01", category="wood")
+
+            # Let's imagine a concrete bench made out of concrete.
+            bench = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture")
+            ifcopenshell.api.run("material.assign_material", model,
+                product=bench, type="IfcMaterial", material=concrete)
+
+            # And some street furniture made from wood.
+            street_furniture = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture")
+            ifcopenshell.api.run("material.assign_material", model,
+                product=street_furniture, type="IfcMaterial", material=wood)
+
+            # Let's copy the concrete over to the street furniture.
+            ifcopenshell.api.run("material.copy_material", model, material=wood, element=street_furniture)
+        """
         self.file = file
-        self.settings = {"material": None, "element": None}
+        self.settings = {"material": material, "element": element}
         for key, value in settings.items():
             self.settings[key] = value