From c3ca969e3201ade5719872befaebb9075d79b17f Mon Sep 17 00:00:00 2001
From: Bruno Postle <bruno@postle.net>
Date: Fri, 20 Mar 2026 21:28:28 +0000
Subject: [PATCH] Doc clarification for api.geometry.add_wall_representation
 clippings normal

Generated with the assistance of an AI coding tool.
---
 .../api/geometry/add_wall_representation.py         |  4 +++-
 .../ifcopenshell/api/geometry/clip_solid.py         | 13 ++++++++++---
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py b/src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py
index ff62bae474..c542471896 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py
@@ -47,7 +47,9 @@ def add_wall_representation(
     :param thickness: The thickness of the wall in meters.
     :param x_angle: The slope angle along the wall's X-axis, in radians.
     :param clippings: List of clipping definitions. Clippings can be `Clipping` objects
-        or dictionaries of arguments for `Clipping.parse`.
+        or dictionaries of arguments for `Clipping.parse`. Each clipping has a
+        ``normal`` that points toward the removed material (the discarded side),
+        not toward the kept material; see :func:`clip_solid` for details.
     :param booleans: List of any existing IfcBooleanResults.
     :return: IfcShapeRepresentation.
     """
diff --git a/src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid.py b/src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid.py
index 283727737e..32f8fc0c96 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid.py
@@ -29,13 +29,20 @@ def clip_solid(
     item: ifcopenshell.entity_instance,
     location: Sequence[float],
     normal: Sequence[float],
+    element: Optional[ifcopenshell.entity_instance] = None,
 ) -> ifcopenshell.entity_instance:
     """Clip a solid with a half-space plane, returning an IfcBooleanClippingResult.
 
     Convenience wrapper around :class:`ifcopenshell.util.data.Clipping` for
-    use with any solid.  The ``normal`` points toward the **removed** material
-    (the void side); the kept region is on the opposite side.  This is the same
-    convention used by the ``clippings`` parameter of :func:`add_wall_representation`.
+    use with any solid.  This is the same convention used by the ``clippings``
+    parameter of :func:`add_wall_representation`.
+
+    .. warning::
+
+        The ``normal`` points toward the **removed** material (the discarded
+        side), not toward the kept material.  For a slope clip the normal
+        points upward into the removed wedge above the slope line.  For a
+        side mitre the normal points outward away from the wall body.
 
     After clipping, set the parent ``IfcShapeRepresentation``
     ``RepresentationType`` to ``"Clipping"``.