From d3795c9836804e37adfb03ad299886724afbd429 Mon Sep 17 00:00:00 2001
From: Sigma Dimensions <79010126+myoualid@users.noreply.github.com>
Date: Mon, 15 Aug 2022 19:40:20 +0100
Subject: [PATCH] Documentation for ifcopenshell.util.element

---
 .../ifcopenshell/util/element.py              | 103 ++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/src/ifcopenshell-python/ifcopenshell/util/element.py b/src/ifcopenshell-python/ifcopenshell/util/element.py
index 49e56493f8..03d7cadb3d 100644
--- a/src/ifcopenshell-python/ifcopenshell/util/element.py
+++ b/src/ifcopenshell-python/ifcopenshell/util/element.py
@@ -20,6 +20,20 @@ import ifcopenshell
 
 
 def get_psets(element, psets_only=False, qtos_only=False, should_inherit=True):
+    """Retrieve property sets, their related properties' names & values and ids.
+
+    :param element: The IFC Element entity
+    :param psets_only: Default as False. Set to true if only property sets are needed. 
+    :param qtos_only: Default as False. Set to true if only quantities are needed.
+    :param should_inherit: Default as True. Set to false if you don't want to inherit property sets from the Type.
+    :return: dictionnary: key, value pair of psets' names and their properties' names & values
+
+    Example::
+        element = ifcopenshell.by_type("IfcBuildingElement")[0]
+        psets = ifcopenshell.util.element.get_psets(element, psets_only=True)
+        qsets = ifcopenshell.util.element.get_psets(element, qtos_only=True)
+        psets_and_qtos = ifcopenshell.util.element.get_psets(element)
+    """
     psets = {}
     if element.is_a("IfcTypeObject"):
         for definition in element.HasPropertySets or []:
@@ -93,6 +107,16 @@ def get_properties(properties):
 
 
 def get_predefined_type(element):
+    """
+    Retrieves the PrefefinedType attribute of an element.
+
+    :param element: The IFC Element entity
+    :return: The predefined type of the element
+
+    Example::
+    element = ifcopenshell.by_type("IfcWall")[0]
+    predefined_type = ifcopenshell.util.element.get_predefined_type(element)
+    """
     element_type = get_type(element)
     if element_type:
         predefined_type = getattr(element_type, "PredefinedType", None)
@@ -107,6 +131,16 @@ def get_predefined_type(element):
 
 
 def get_type(element):
+    """
+    Retrieves the Element Type entity related to an element entity.
+    
+    :param element: The IFC Element entity
+    :return: The Element Type entity defining the element
+
+    Example::
+    element = ifcopenshell.by_type("IfcWall")[0]
+    element_type = ifcopenshell.util.element.get_type(element)
+    """
     if element.is_a("IfcTypeObject"):
         return element
     elif hasattr(element, "IsTypedBy") and element.IsTypedBy:
@@ -142,6 +176,17 @@ def get_material(element, should_skip_usage=False, should_inherit=True):
 
 
 def get_elements_by_material(ifc_file, material):
+    """
+    Retrieves the elements related to a material.
+    
+    :param ifc_file: The IFC file
+    :param material: The IFC Material entity
+    :return: The elements related to the material
+
+    Example::
+    material = file.by_type("IfcMaterial")[0]
+    elements = ifcopenshell.util.element.get_elements_by_material(file, material)
+    """
     results = set()
     for inverse in ifc_file.get_inverse(material):
         if inverse.is_a("IfcRelAssociatesMaterial"):
@@ -165,6 +210,18 @@ def get_elements_by_material(ifc_file, material):
 
 
 def get_elements_by_style(ifc_file, style):
+    """
+    Retrieves the elements related to a style.
+    
+    :param ifc_file: The IFC file
+    :param style: The IFC Style entity
+    :return: The elements related to the style
+
+    Example::
+    style = file.by_type("IfcSurfaceStyle")[0]
+    elements = ifcopenshell.util.element.get_elements_by_style(file, style)
+
+    """
     results = set()
     inverses = list(ifc_file.get_inverse(style))
     while inverses:
@@ -224,6 +281,19 @@ def get_layers(ifc_file, element):
 
 
 def get_container(element, should_get_direct=False):
+    """
+    Retrieves the container of an element.
+    
+    :param element: The IFC element
+    :param should_get_direct: If True, the container of the element is returned. If False, the aggregate's container is returned
+    :return: The container of the element, or its aggregate's container.
+
+
+    Example::
+    element = file.by_type("IfcWall")[0]
+    container = ifcopenshell.util.element.get_container(element)
+
+    """
     if should_get_direct:
         if hasattr(element, "ContainedInStructure") and element.ContainedInStructure:
             return element.ContainedInStructure[0].RelatingStructure
@@ -236,6 +306,17 @@ def get_container(element, should_get_direct=False):
 
 
 def get_decomposition(element):
+    """
+    Retrieves the decomposition of an element.
+    
+    :param element: The IFC element
+    :return: The decomposition of the element
+
+    Example::
+    element = file.by_type("IfcProject")[0]
+    decomposition = ifcopenshell.util.element.get_decomposition(element)
+
+    """
     queue = [element]
     results = []
     while queue:
@@ -250,11 +331,33 @@ def get_decomposition(element):
 
 
 def get_aggregate(element):
+    """
+    Retrieves the aggregate of an element.
+    
+    :param element: The IFC element
+    :return: The aggregate of the element
+
+    Example::
+    element = file.by_type("IfcBeam")[0]
+    aggregate = ifcopenshell.util.element.get_aggregate(element)
+
+    """
     if hasattr(element, "Decomposes") and element.Decomposes:
         return element.Decomposes[0].RelatingObject
 
 
 def get_parts(element):
+    """
+    Retrieves the parts of an element.
+    
+    :param element: The IFC element
+    :return: The parts of the element
+
+    Example::
+    element = file.by_type("IfcElementAssembly")[0]
+    parts = ifcopenshell.util.element.get_parts(element)
+    
+    """
     if hasattr(element, "IsDecomposedBy") and element.IsDecomposedBy:
         return element.IsDecomposedBy[0].RelatedObjects