Add API documentation for the material module

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

@@ -18,9 +18,43 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, material_set=None, old_index=0, new_index=0):
+        """Reorders an item in a material set
+
+        In some material sets, the order have meaning, like in a layer set. In
+        other cases, it is purely for human convenience.
+
+        :param material_set: The IfcMaterialSet which you want to reorder an
+            item in.
+        :type material_set: ifcopenshell.entity_instance.entity_instance
+        :param old_index: The index of the item you want to move. This starts
+            counting from 0.
+        :type old_index: int
+        :param new_index: The index of the new position the item will move to.
+            This starts counting from 0.
+        :type new_index: int
+        :return: None
+        :rtype: None
+
+        Example::
+
+            material_set = ifcopenshell.api.run("material.add_material_set", model,
+                name="Window", set_type="IfcMaterialList")
+
+            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 items in our list.
+            ifcopenshell.api.run("material.add_list_item", model, material_list=material_set, material=aluminium)
+            ifcopenshell.api.run("material.add_list_item", model, material_list=material_set, material=glass)
+
+            # Switch the order around, this has no meaning for a list, so this
+            # is just for fun.
+            ifcopenshell.api.run("material.reorder_set_item", model,
+                material_set=material_set, old_index=0, new_index=1)
+        """
         self.file = file
-        self.settings = {"material_set": None, "old_index": 0, "new_index": 0}
+        self.settings = {"material_set": material_set, "old_index": old_index, "new_index": new_index}
         for key, value in settings.items():
             self.settings[key] = value