Update incorrect docs and raise suspicion about how shape aspect styles are assigned

src/bonsai/bonsai/bim/module/geometry/operator.py

@@ -2671,12 +2671,13 @@ class EditRepresentationItemShapeAspect(bpy.types.Operator, tool.Ifc.Operator):
             shape_aspect, representation_item
         )
         styles = tool.Geometry.get_shape_aspect_styles(element, shape_aspect, representation_item)
+        # TODO this looks wrong to me. In theory styles can be > 1 (e.g. curve
+        # styles) and then the usecase will assign the wrong style.
         tool.Ifc.run(
             "style.assign_representation_styles",
             shape_representation=shape_aspect_representation,
             styles=styles,
         )
-        tool.Geometry.get_shape_aspect_styles(element, shape_aspect, representation_item)
         tool.Geometry.reload_representation(obj)
 
         # reload items ui

src/ifcopenshell-python/ifcopenshell/api/style/assign_item_style.py

@@ -55,7 +55,7 @@ def assign_item_style(
         body = ifcopenshell.api.context.add_context(model,
             context_type="Model", context_identifier="Body", target_view="MODEL_VIEW", parent=model3d)
 
-        # Let's create a new wall. The wall does not have any geometry yet.
+        # Let's create a new block shaped furniture. The furniture does not have any geometry yet.
         wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")
 
         # Let's use the "3D Body" representation we created earlier to add a
@@ -81,9 +81,9 @@ def assign_item_style(
                 "Transparency": 0., # 0 is opaque, 1 is transparent
             })
 
-        # Now specifically our wall only will be coloured grey.
-        ifcopenshell.api.style.assign_representation_styles(model,
-            shape_representation=representation, styles=[style])
+        # Now specifically our wall's only item only will be coloured grey.
+        ifcopenshell.api.style.assign_item_style(model,
+            shape_representation=representation, style=style, item=representation.Items[0])
     """
     if not (styled_item := next(iter(item.StyledByItem), None)):
         if style is None:

src/ifcopenshell-python/ifcopenshell/api/style/assign_representation_styles.py

@@ -36,6 +36,11 @@ def assign_representation_styles(
     to the object representation as an override. This API function provides
     that capability.
 
+    This function assigns styles in bulk in an ordered manner to every item in
+    the representation, so the order and total styles provided is significant.
+    If you want more granular control, use
+    :func:`ifcopenshell.api.style.assign_item_style`.
+
     If you want to assign styles to a material instead (recommended), then
     please see ifcopenshell.api.style.assign_material_style.