Add API documentation for group module

src/ifcopenshell-python/ifcopenshell/api/group/add_group.py

@@ -21,14 +21,33 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, Name="Unnamed", Description=None):
+        """Adds a new group
+
+        An IFC group is an arbitrary collection of products, which are typically
+        physical. It may be used when there is no other more specific group
+        which may be used. Other types of groups include distribution systems,
+        which group together products that are connected and circulate a medium
+        (such as fluid or electricity), or zones, which group together spaces,
+        or structural load groups, which group together loads for structural
+        analysis, or inventories, which are groups of assets.
+
+        :param Name: The name of the group. Defaults to "Unnamed"
+        :type Name: str, optional
+        :param Description: The description of the purpose of the group.
+        :type Description: str, optional
+        :return: The newly created IfcGroup
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            ifcopenshell.api.run("group.add_group", model, Name="Unit 1A")
+        """
         self.file = file
         self.settings = {
-            "Name": "Unnamed",
+            "Name": Name or "Unnamed",
-            "Description": "",
+            "Description": Description,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         return self.file.create_entity(

src/ifcopenshell-python/ifcopenshell/api/group/assign_group.py

@@ -21,14 +21,30 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, products=None, group=None):
+        """Assigns products to a group
+
+        If a product is already assigned to the group, it will not be assigned
+        twice.
+
+        :param products: A list of IfcProduct elements to assign to the group
+        :type products: list[ifcopenshell.entity_instance.entity_instance]
+        :param group: The IfcGroup to assign the products to
+        :type group: ifcopenshell.entity_instance.entity_instance
+        :return: The IfcRelAssignsToGroup relationship
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            group = ifcopenshell.api.run("group.add_group", model, Name="Furniture")
+            ifcopenshell.api.run("group.assign_group", model,
+                products=model.by_type("IfcFurniture"), group=group)
+        """
         self.file = file
         self.settings = {
-            "products": None,
+            "products": products,
-            "group": None,
+            "group": group,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if not self.settings["group"].IsGroupedBy:

src/ifcopenshell-python/ifcopenshell/api/group/edit_group.py

@@ -18,12 +18,28 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, group=None, attributes=None):
+        """Edits the attributes of an IfcGroup
+
+        For more information about the attributes and data types of an
+        IfcGroup, consult the IFC documentation.
+
+        :param group: The IfcGroup entity you want to edit
+        :type group: ifcopenshell.entity_instance.entity_instance
+        :param attributes: a dictionary of attribute names and values.
+        :type attributes: dict, optional
+        :return: None
+        :rtype: None
+
+        Example::
+
+            group = ifcopenshell.api.run("group.add_group", model, Name="Unit 1A")
+            ifcopenshell.api.run("group.edit_group", model,
+                group=group, attributes={"Description": "All furniture and joinery included in the unit"})
+        """
+
         self.file = file
-        self.settings = {
+        self.settings = {"group": group, "attributes": attributes or {}}
-            "group": None, "attributes": {}}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for name, value in self.settings["attributes"].items():

src/ifcopenshell-python/ifcopenshell/api/group/remove_group.py

@@ -18,11 +18,24 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, group=None):
+        """Removes a group
+
+        All products assigned to the group will remain, but the relationship to
+        the group will be removed.
+
+        :param group: The IfcGroup entity you want to remove
+        :type group: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            group = ifcopenshell.api.run("group.add_group", model, Name="Unit 1A")
+            ifcopenshell.api.run("group.remove_group", model, group=group)
+        """
         self.file = file
-        self.settings = {"group": None}
+        self.settings = {"group": group}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         for rel in self.settings["group"].IsGroupedBy or []:

src/ifcopenshell-python/ifcopenshell/api/group/unassign_group.py

@@ -21,14 +21,32 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, product=None, group=None):
+        """Unassigns a product from a group
+
+        If the product isn't assigned to the group, nothing will happen.
+
+        :param product: A IfcProduct element to unassign from the group
+        :type product: ifcopenshell.entity_instance.entity_instance
+        :param group: The IfcGroup to assign the products to
+        :type group: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            group = ifcopenshell.api.run("group.add_group", model, Name="Furniture")
+            furniture = model.by_type("IfcFurniture")
+            ifcopenshell.api.run("group.assign_group", model, products=furniture, group=group)
+
+            bad_furniture = furniture[0]
+            ifcopenshell.api.run("group.unassign_group", model, product=bad_furniture, group=group)
+        """
         self.file = file
         self.settings = {
-            "product": None,
+            "product": product,
-            "group": None,
+            "group": group,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if not self.settings["group"].IsGroupedBy:

src/ifcopenshell-python/ifcopenshell/api/group/update_group_products.py

@@ -21,14 +21,30 @@ import ifcopenshell.api
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, group=None, products=None):
+        """Sets a group products to be an explicit list of products
+
+        Any previous products assigned to that group will have their assignment
+        removed.
+
+        :param products: A list of IfcProduct elements to assign to the group
+        :type products: list[ifcopenshell.entity_instance.entity_instance]
+        :param group: The IfcGroup to assign the products to
+        :type group: ifcopenshell.entity_instance.entity_instance
+        :return: The IfcRelAssignsToGroup relationship
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            group = ifcopenshell.api.run("group.add_group", model, Name="Furniture")
+            ifcopenshell.api.run("group.update_group_products", model,
+                products=model.by_type("IfcFurniture"), group=group)
+        """
         self.file = file
         self.settings = {
-            "group": None,
+            "group": group,
-            "products": None,
+            "products": products,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if not self.settings["group"].IsGroupedBy: