Add documentation for pset API module

src/ifcopenshell-python/ifcopenshell/api/pset/add_qto.py

@@ -21,11 +21,63 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, name=None):
+        """Adds a new quantity set to a product
+
+        Products, such as physical objects or types in IFC may have quantities
+        associated with them. These quantities are typically simple key value
+        metadata with data types. For example, a wall type may have a quantity
+        called NetSideArea with a area value of "4.2". Quantities are grouped
+        into quantity sets, so that related quantities are grouped together.
+
+        Quantities can only be assigned to occurrences, not types.
+
+        Quantities are similar to, but different from properties in that they
+        may store a method of measurement or formula. Quantities may also have
+        parametric relationships to other calculated values, such as cost
+        schedules, resource utilisation, or construction task durations.
+
+        buildingSMART has come up with a long list of standardised quantities
+        for the most common quantities required internationally. This solves the
+        age-old question of "what's the standard way of storing quantity
+        take-off data"? It is recommended to view the list of standardised
+        buildingSMART quantities and see if any suit your needs first. If none
+        are appropriate, then you are free to create your own custom quantities.
+
+        This function adds a blank named quantity set. One you have a quantity
+        set you may add quantities using ifcopenshell.api.pset.edit_qto.
+
+        See also ifcopenshell.api.pset.add_qto if you want to arbitrary
+        metadata, rather than quantification data.
+
+        :param product: The IfcObject that you want to assign a quantity set to.
+        :type product: ifcopenshell.entity_instance.entity_instance
+        :param name: The name of the quantity set. Quantity sets that are
+            standardised by buildingSMART typically have a prefix of "Qto_",
+            like "Qto_WallBaseQuantities". If you create your own, you must not
+            use that prefix. It is recommended to use your own prefix tailored
+            to your project, company, or local government requirement.
+        :type name: str
+        :return: The newly created IfcElementQuantity
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            # Let's imagine we have a new wall.
+            wall = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcWall")
+
+            # Note that this only creates and assigns an empty quantity set. We
+            # still need to add quantities into the property set. Having blank
+            # quantity sets are invalid.
+            qto = ifcopenshell.api.run("pset.add_qto", model, product=wall_type, name="Qto_WallBaseQuantities")
+
+            # Add a side area property standardised by buildingSMART. This
+            # allows quantity take-off to occur, even though no geometry has
+            # even been modelled!
+            ifcopenshell.api.run("pset.edit_qto", model, qto=qto, properties={"NetSideArea": 4.2})
+        """
         self.file = file
-        self.settings = {"product": None, "name": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"product": product, "name": name}
 
     def execute(self):
         if self.settings["product"].is_a("IfcObject") or self.settings["product"].is_a("IfcContext"):