Write docs for owner API module

src/ifcopenshell-python/ifcopenshell/api/owner/add_role.py

@@ -18,14 +18,43 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, assigned_object=None, role="ARCHITECT"):
+        """Adds and assigns a new role
+
+        People and organisations must play one or more roles on a project. Roles
+        include architects, engineers, subcontractors, clients, manufacturers,
+        etc. Typically these roles and their corresponding responsibilities will
+        be outlined in contractual documents.
+
+        This function will both add and assign the role to the person or
+        organisation.
+
+        :param assigned_object: The IfcPerson or IfcOrganization the role should
+            be assigned to.
+        :type assigned_object: ifcopenshell.entity_instance.entity_instance
+        :param role: The type of role, taken from the IFC documentation for
+            IfcActorRole, or a custom name.
+        :type role: str, optional
+        :return: The newly created IfcActorRole
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example::
+
+            organisation = ifcopenshell.api.run("owner.add_organisation", model,
+                identification="AWB", name="Architects Without Ballpens")
+            ifcopenshell.api.run("owner.add_role", model, assigned_object=organisation, role="ARCHITECT")
+        """
         self.file = file
-        self.settings = {"assigned_object": None}
-        for key, value in settings.items():
-            self.settings[key] = value
+        self.settings = {"assigned_object": assigned_object, "role": role}
 
     def execute(self):
         element = self.file.createIfcActorRole("ARCHITECT")
+        if self.settings["role"]:
+            try:
+                element.Role = self.settings["role"]
+            except:
+                element.Role = "USERDEFINED"
+                element.UserDefinedRole = self.settings["role"]
         roles = list(self.settings["assigned_object"].Roles) if self.settings["assigned_object"].Roles else []
         roles.append(element)
         self.settings["assigned_object"].Roles = roles