Add API documentation for classification module

src/ifcopenshell-python/ifcopenshell/api/classification/add_classification.py

@@ -22,13 +22,62 @@ import ifcopenshell.util.date
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, classification=None):
+        """Adds a new classification system to the project
+
+        External classification systems such as Uniclass or Omniclass are
+        ways of categorising elements in the AEC industry, typically
+        standardised or nominated by governments or companies. A system
+        typically contains a series of hierarchical reference codes and labels
+        like Pr_12_23_34.
+
+        Classifications may be applied to many things, not just physical
+        elements, such as doors and windows, spatial elements, tasks, cost
+        items, or even resources.
+
+        Prior to assigning classificaion references, you need to add the name
+        and metadata of the classification system that you will use in your
+        project. Classification systems may be revised over time, so this
+        metadata includes the edition date.
+
+        Common classification systems are provided as an IFC library which may
+        be downloaded from https://github.com/Moult/IfcClassification for your
+        convenience. It is advised to use these to ensure that the
+        classification metadata is standardised.
+
+        Adding a classification system will not add the entire hierarchy of
+        references available in the classification. References need to be added
+        separately. Typically, you'd only add the references that you use in
+        your project, see ifcopenshell.api.classification.add_reference for more
+        information.
+
+        :param classification: If a string is provided, it is assumed to be the
+            name of your classification system. This is necessary if you are
+            creating your own custom classification system. Alternatively, you
+            may provide an entity_instance of an IfcClassification from an IFC
+            classification library. The latter approach is preferred if you are
+            using a commonly known system such as Uniclass, as this will ensure
+            all metadata is added correctly.
+        :type classification: str,ifcopenshell.entity_instance.entity_instance
+        :return: The added IfcClassification element
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Option 1: adding a custom clasification from scratch
+            ifcopenshell.api.run("classification.add_classification", model,
+                classification="MyCustomClassification")
+
+            # Option 2: adding a popular classification from a library
+            library = ifcopenshell.open("/path/to/Uniclass.ifc")
+            classification = library.by_type("IfcClassification")[0]
+            ifcopenshell.api.run("classification.add_classification", model,
+                classification=classification)
+        """
         self.file = file
         self.settings = {
-            "classification": None,
+            "classification": classification,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if isinstance(self.settings["classification"], str):