From 4e308a6e313a2b748d2e3f01ba59c4908c5421a1 Mon Sep 17 00:00:00 2001
From: Sigma Dimensions <79010126+myoualid@users.noreply.github.com>
Date: Tue, 7 Feb 2023 15:35:34 +0100
Subject: [PATCH] fix api docstring description for nest.unassign_object
 usecase

---
 .../ifcopenshell/api/nest/unassign_object.py  | 39 ++++++++-----------
 1 file changed, 16 insertions(+), 23 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/api/nest/unassign_object.py b/src/ifcopenshell-python/ifcopenshell/api/nest/unassign_object.py
index 335863d690..97391d8619 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/nest/unassign_object.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/nest/unassign_object.py
@@ -22,26 +22,17 @@ import ifcopenshell.api
 
 class Usecase:
     def __init__(self, file, related_object=None):
-        """Unassigns a related_object from its nest
-
-        A related_object (i.e. a smaller part of a whole) may be aggregated into zero
-        or one larger space or task. This function will remove that
-        aggregation relationship.
-
-        As all physical IFC model elements must be part of a hierarchical tree
-        called the "spatial decomposition", using this function will remove the
-        related_object from that tree. This is a dangerous operation and may result in
-        the related_object no longer being visible in IFC applications.
-
-        If the related_object is not part of an aggregation relationship, nothing will
-        happen.
-
-        :param related_object: The part of the nest, typically an IfcElement or
-            IfcSpatialStructureElement subclass
+        """Unassigns a related_object from its nest.
+        
+        An object (the whole within a decomposition) is Nested by zero or one more smaller objects.
+        This function will remove this nesting relationship.
+        
+        If the object is not part of a nesting relationship, nothing will happen.
+        
+        :param related_object: The child of the nesting relationship, typically
+            an IfcElement.
         :type related_object: ifcopenshell.entity_instance.entity_instance
-        :return: The IfcRelAggregate relationship instance, only returned if the
-            whole still contains any other parts.
-        :rtype: ifcopenshell.entity_instance.entity_instance, None
+        :return: None if the nest has only one child, otherwise the IfcRelNests relationship instance
 
         Example:
 
@@ -54,11 +45,11 @@ class Usecase:
             ifcopenshell.api.run("nest.assign_object", model, related_object=subtask2, relating_object=task)
             # The relationship is returned as task still has subtask2
             rel = ifcopenshell.api.run("nest.unassign_object", model, related_object=subtask1)
-            # Nothing is returned, as task is now empty
+            # Nothing is returned, as the relationship has no related objects
             ifcopenshell.api.run("nest.unassign_object", model, related_object=subtask2)
         """
         self.file = file
-        self.settings = { "related_object": related_object }
+        self.settings = {"related_object": related_object}
 
     def execute(self):
         for rel in self.settings["related_object"].Nests or []:
@@ -69,5 +60,7 @@ class Usecase:
             related_objects = list(rel.RelatedObjects)
             related_objects.remove(self.settings["related_object"])
             rel.RelatedObjects = related_objects
-            ifcopenshell.api.run("owner.update_owner_history", self.file, **{"element": rel})
-            return rel
\ No newline at end of file
+            ifcopenshell.api.run(
+                "owner.update_owner_history", self.file, **{"element": rel}
+            )
+            return rel