add_slab_representation - add api description #5792

src/ifcopenshell-python/ifcopenshell/api/geometry/add_slab_representation.py

@@ -16,6 +16,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+import ifcopenshell.util.element
 import ifcopenshell.util.unit
 from ifcopenshell.util.data import Clipping
 from math import sin, cos
@@ -23,19 +24,33 @@ from typing import Any, Optional, Union
 
 
 def add_slab_representation(
-    file,
+    file: ifcopenshell.file,
-    # IfcGeometricRepresentationContext
     context: ifcopenshell.entity_instance,
-    # in meters
     depth: float = 0.2,
-    # in radians
     x_angle: float = 0.0,
-    # A list of planes that define clipping half space solids
-    # Planes are defined either by Clipping objects
-    # or by dictionaries of arguments for `Clipping.parse`
     clippings: Optional[list[Union[Clipping, dict[str, Any]]]] = None,
-    polyline: Optional[list[tuple]] = None,
+    polyline: Optional[list[tuple[float, float]]] = None,
 ) -> ifcopenshell.entity_instance:
+    """
+    Add a geometric representation for a slab.
+
+    :param context: The IfcGeometricRepresentationContext for the representation,
+        only Model/Body/MODEL_VIEW type of representations are currently supported.
+    :param depth: The slab depth, in meters.
+    :param x_angle: The slope angle along the slab's X-axis, in radians.
+    :param clippings: List of planes that define clipping half space solids.
+        Clippings can be `Clipping` objects or dictionaries of arguments for `Clipping.parse`.
+    :return: IfcShapeRepresentation.
+
+    Example:
+
+    .. code:: python
+
+        context = ifcopenshell.util.representation.get_context(ifc_file, "Model", "Body", "MODEL_VIEW")
+        clippings = [ifcopenshell.util.data.Clipping(location=(0.0, 0.0, 0.1), normal=(0.0, 0.0, 1.0),)]
+        representation = ifcopenshell.api.geometry.add_slab_representation(ifc_file, context, depth=0.2, clippings=clippings)
+        ifcopenshell.api.geometry.assign_representation(ifc_file, product=element, representation=representation)
+    """
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
@@ -49,6 +64,9 @@ def add_slab_representation(
 
 
 class Usecase:
+    file: ifcopenshell.file
+    settings: dict[str, Any]
+
     def execute(self):
         self.settings["unit_scale"] = ifcopenshell.util.unit.calculate_unit_scale(self.file)
         return self.file.createIfcShapeRepresentation(