From 10d30b0de72527fef4dce37f584478f564f38107 Mon Sep 17 00:00:00 2001
From: Dion Moult <dion@thinkmoult.com>
Date: Wed, 8 May 2024 17:00:35 +1000
Subject: [PATCH] Document api modules and require explicit imports of API
 submodules

---
 .../ifcopenshell/api/__init__.py              | 58 ++++---------------
 .../ifcopenshell/api/aggregate/__init__.py    | 11 ++--
 .../ifcopenshell/api/attribute/__init__.py    | 10 ++++
 .../ifcopenshell/api/boundary/__init__.py     |  6 ++
 .../api/classification/__init__.py            | 14 +++++
 .../ifcopenshell/api/constraint/__init__.py   |  9 +++
 .../ifcopenshell/api/context/__init__.py      | 12 ++++
 .../ifcopenshell/api/control/__init__.py      |  9 +++
 .../ifcopenshell/api/cost/__init__.py         | 11 ++++
 .../ifcopenshell/api/document/__init__.py     | 11 ++++
 .../ifcopenshell/api/drawing/__init__.py      |  9 +++
 .../ifcopenshell/api/geometry/__init__.py     | 10 ++++
 .../ifcopenshell/api/georeference/__init__.py | 10 ++++
 .../ifcopenshell/api/grid/__init__.py         |  8 +++
 .../ifcopenshell/api/group/__init__.py        | 10 ++++
 .../ifcopenshell/api/layer/__init__.py        | 12 ++++
 .../ifcopenshell/api/library/__init__.py      | 10 ++++
 .../ifcopenshell/api/material/__init__.py     | 18 ++++++
 .../ifcopenshell/api/nest/__init__.py         | 14 +++++
 .../ifcopenshell/api/owner/__init__.py        | 11 ++++
 .../ifcopenshell/api/profile/__init__.py      |  9 +++
 .../ifcopenshell/api/project/__init__.py      | 13 +++++
 .../ifcopenshell/api/pset/__init__.py         | 10 ++++
 .../api/pset_template/__init__.py             | 11 ++++
 .../ifcopenshell/api/resource/__init__.py     | 10 ++++
 .../ifcopenshell/api/root/__init__.py         | 13 +++++
 .../ifcopenshell/api/sequence/__init__.py     |  9 +++
 .../ifcopenshell/api/spatial/__init__.py      |  9 +++
 .../ifcopenshell/api/structural/__init__.py   |  9 +++
 .../ifcopenshell/api/style/__init__.py        | 10 ++++
 .../ifcopenshell/api/system/__init__.py       | 11 ++++
 .../ifcopenshell/api/type/__init__.py         | 11 ++++
 .../ifcopenshell/api/unit/__init__.py         | 10 ++++
 .../ifcopenshell/api/void/__init__.py         | 11 ++++
 34 files changed, 358 insertions(+), 51 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/api/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/__init__.py
index 2e6e2c1370..e24870d956 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/__init__.py
@@ -27,7 +27,6 @@ relationships are all handled automatically.
 
 import json
 import numpy
-import pkgutil
 import inspect
 import importlib
 import ifcopenshell
@@ -328,50 +327,15 @@ def wrap_usecase(usecase_path, usecase):
     return wrapper
 
 
-# Expose all submodules. This means that the user can just type `import ifcopenshell.api`.
-import ifcopenshell.api.aggregate as aggregate
-import ifcopenshell.api.attribute as attribute
-import ifcopenshell.api.boundary as boundary
-import ifcopenshell.api.classification as classification
-import ifcopenshell.api.constraint as constraint
-import ifcopenshell.api.context as context
-import ifcopenshell.api.control as control
-import ifcopenshell.api.cost as cost
-import ifcopenshell.api.document as document
-import ifcopenshell.api.drawing as drawing
-import ifcopenshell.api.geometry as geometry
-import ifcopenshell.api.georeference as georeference
-import ifcopenshell.api.grid as grid
-import ifcopenshell.api.group as group
-import ifcopenshell.api.layer as layer
-import ifcopenshell.api.library as library
-import ifcopenshell.api.material as material
-import ifcopenshell.api.nest as nest
-import ifcopenshell.api.owner as owner
-import ifcopenshell.api.profile as profile
-import ifcopenshell.api.project as project
-import ifcopenshell.api.pset as pset
-import ifcopenshell.api.pset_template as pset_template
-import ifcopenshell.api.resource as resource
-import ifcopenshell.api.root as root
-import ifcopenshell.api.sequence as sequence
-import ifcopenshell.api.spatial as spatial
-import ifcopenshell.api.structural as structural
-import ifcopenshell.api.style as style
-import ifcopenshell.api.system as system
-import ifcopenshell.api.type as type  # Whoohoo!
-import ifcopenshell.api.unit as unit
-import ifcopenshell.api.void as void
+def wrap_usecases(path, name):
+    """This developer feature wraps an API module's usecases with listeners."""
+    import sys
+    import pkgutil
 
-# Wrap all submodule usecases with listeners.
-# This for loop also conveniently ensures that the above imports are comprehensive.
-for loader, module_name, is_pkg in pkgutil.iter_modules(__path__, __name__ + "."):
-    # Check if it's a direct child (only one level deep)
-    if module_name.count(".") == __name__.count(".") + 1:
-        module_name = module_name.split(".")[-1]
-        module = globals()[module_name]
-        for usecase_name in vars(module):
-            usecase = getattr(module, usecase_name)
-            if callable(usecase):
-                usecase_path = f"{module_name}.{usecase_name}"
-                setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))
+    module_name = name.split(".")[-1]
+    module = sys.modules[name]
+    for loader, usecase_name, is_pkg in pkgutil.iter_modules(path):
+        usecase = getattr(module, usecase_name)
+        if callable(usecase):
+            usecase_path = f"{module_name}.{usecase_name}"
+            setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))
diff --git a/src/ifcopenshell-python/ifcopenshell/api/aggregate/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/aggregate/__init__.py
index bf452c8e2b..21630a9be4 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/aggregate/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/aggregate/__init__.py
@@ -16,12 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Aggregates are the concept of breaking down larger wholes into smaller parts.
+"""Aggregates is the concept of breaking down larger wholes into smaller parts.
 
-One common use is spatial elements, such as how a site has multiple buildings,
-and a building has multiple storeys. Another is for regular elements, such as
-how a wall is made out of members and coverings.
+For example, spatial elements such as sites are broken down into one or more
+buildings, and a building is broken down into storeys. Another example is for
+physical elements, such as how a wall is made out of members and coverings.
 """
 
+from .. import wrap_usecases
 from .assign_object import assign_object
 from .unassign_object import unassign_object
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/attribute/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/attribute/__init__.py
index 31a605de5d..6d1164b4bd 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/attribute/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/attribute/__init__.py
@@ -16,4 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Basic modification of the attributes of an element.
+
+All IFC entities have attributes. Some of these attributes contain rules about
+inheritance and what they are allowed to contain. These usecases make sure that
+any editing complies with these rules.
+"""
+
+from .. import wrap_usecases
 from .edit_attributes import edit_attributes
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/boundary/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/boundary/__init__.py
index fff4c4e7f5..027c2cf00b 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/boundary/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/boundary/__init__.py
@@ -18,9 +18,15 @@
 
 """Boundaries are primarily used for representing virtual interfaces between
 spaces for energy analysis.
+
+Boundaries may be associated with spaces or physical elements that enclose
+spaces such as walls, doors, and windows.
 """
 
+from .. import wrap_usecases
 from .assign_connection_geometry import assign_connection_geometry
 from .copy_boundary import copy_boundary
 from .edit_attributes import edit_attributes
 from .remove_boundary import remove_boundary
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/classification/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/classification/__init__.py
index 6616ff6f89..1ad42def0c 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/classification/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/classification/__init__.py
@@ -16,9 +16,23 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Classification systems are a way of categorising objects
+
+Although IFC itself comes with a built-in classification hierarchy (e.g.
+IfcWall and its predefined types of PARTITIONING, etc), there are many external
+or custom classification systems such as Uniclass, Omniclass and more. IFC is
+able to integrate with any external classification system.
+
+This API allows you to manage and assign external classification systems and
+references.
+"""
+
+from .. import wrap_usecases
 from .add_classification import add_classification
 from .add_reference import add_reference
 from .edit_classification import edit_classification
 from .edit_reference import edit_reference
 from .remove_classification import remove_classification
 from .remove_reference import remove_reference
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/__init__.py
index 7309050851..3e17e6a708 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/constraint/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/__init__.py
@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Constraints are an advanced feature allowing you to specify parametric
+limits on properties
+
+Warning: usage of constraints are mostly untested in real life applications.
+"""
+
+from .. import wrap_usecases
 from .add_metric import add_metric
 from .add_metric_reference import add_metric_reference
 from .add_objective import add_objective
@@ -25,3 +32,5 @@ from .edit_objective import edit_objective
 from .remove_constraint import remove_constraint
 from .remove_metric import remove_metric
 from .unassign_constraint import unassign_constraint
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/context/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/context/__init__.py
index 1edb3ee252..556d45145c 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/context/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/context/__init__.py
@@ -16,6 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Contexts allow you to classify when geometry should be used in different
+purposes
+
+For example, a door may have many geometries assigned to it: a 3D body
+geometry, a clearance zone for disabled access and egress, and a 2D top down
+plan view representation annotating swing extents. Each geometry is assigned to
+a context to distinguish its purpose and level of detail.
+"""
+
+from .. import wrap_usecases
 from .add_context import add_context
 from .edit_context import edit_context
 from .remove_context import remove_context
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/control/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/control/__init__.py
index 792f5eec35..7aa970005e 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/control/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/control/__init__.py
@@ -16,5 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Processes and costs may be controlled by other entities which indicate
+constraints that determine how they can change
+
+This is an advanced feature mostly used in 4D/5D
+"""
+
+from .. import wrap_usecases
 from .assign_control import assign_control
 from .unassign_control import unassign_control
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/cost/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/cost/__init__.py
index 4cf5fc63c6..713f243c4a 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/cost/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/cost/__init__.py
@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage cost schedules, cost items, cost estimation and parametric quantity
+take-off
+
+IFC supports storing cost schedules and detailed cost breakdown structures,
+including formulas, subtotals, and parametric links to model element
+quantities.
+"""
+
+from .. import wrap_usecases
 from .add_cost_item import add_cost_item
 from .add_cost_item_quantity import add_cost_item_quantity
 from .add_cost_schedule import add_cost_schedule
@@ -35,3 +44,5 @@ from .remove_cost_item_quantity import remove_cost_item_quantity
 from .remove_cost_schedule import remove_cost_schedule
 from .remove_cost_value import remove_cost_value
 from .unassign_cost_item_quantity import unassign_cost_item_quantity
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/document/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/document/__init__.py
index b1affe3a71..0e18a16fee 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/document/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/document/__init__.py
@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Reference external project documents and associate them to model elements
+
+Some project information (drawings, specifications, certificates, reports, etc)
+may be stored in external documents (locally or in a CDE). IFC lets you store a
+register of documents with metadata and associate them with elements (both
+physical and non-physical).
+"""
+
+from .. import wrap_usecases
 from .add_information import add_information
 from .add_reference import add_reference
 from .assign_document import assign_document
@@ -24,3 +33,5 @@ from .edit_reference import edit_reference
 from .remove_information import remove_information
 from .remove_reference import remove_reference
 from .unassign_document import unassign_document
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/drawing/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/drawing/__init__.py
index dd010e886e..50c8838cd6 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/drawing/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/drawing/__init__.py
@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create relationships necessary for smart annotations for drawings
+
+Drawings may be generated from modeled elements and annotations. These
+annotations may have relationships which indicate smart data being populated.
+"""
+
+from .. import wrap_usecases
 from .assign_product import assign_product
 from .edit_text_literal import edit_text_literal
 from .unassign_product import unassign_product
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py
index 0aa8756ea0..e0b6f83319 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py
@@ -16,6 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create geometric representations and assign them to elements
+
+These functions support both the creation of arbitrary geometry as well as
+geometry that follows parametric rules (e.g. layered geometry or profiled
+geometry extrusions).
+"""
+
+from .. import wrap_usecases
 from .add_axis_representation import add_axis_representation
 from .add_boolean import add_boolean
 try:
@@ -51,3 +59,5 @@ from .map_representation import map_representation
 from .remove_boolean import remove_boolean
 from .remove_representation import remove_representation
 from .unassign_representation import unassign_representation
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/georeference/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/georeference/__init__.py
index 1aa858db17..5488015977 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/georeference/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/georeference/__init__.py
@@ -16,6 +16,16 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage georeferencing metadata
+
+IFC model geometry may have a coordinate reference system (CRS) assigned to it.
+It may also optionally have a map conversion defined to transform to and from
+map coordinates and project local engineering coordinates.
+"""
+
+from .. import wrap_usecases
 from .add_georeferencing import add_georeferencing
 from .edit_georeferencing import edit_georeferencing
 from .remove_georeferencing import remove_georeferencing
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/grid/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/grid/__init__.py
index 9991a7bc06..bdbe764870 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/grid/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/grid/__init__.py
@@ -16,9 +16,17 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manages grid and grid axes
+
+A grid in IFC may contain two or more axes running in two or more directions.
+"""
+
+from .. import wrap_usecases
 try:
     from .create_axis_curve import create_axis_curve
 except ModuleNotFoundError as e:
     print(f"Note: API not available due to missing dependencies: grid.create_axis_curve - {e}")
 from .create_grid_axis import create_grid_axis
 from .remove_grid_axis import remove_grid_axis
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/group/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/group/__init__.py
index 5b729b0dfc..e5f9c9db67 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/group/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/group/__init__.py
@@ -16,9 +16,19 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Elements may be arbitrarily assigned to groups for organisation
+
+Groups are useful for filtering elements or non-hierarchical organisation of a
+model. Note that this only targets arbitrary groups. If you want to group
+elements into a distribution system, see :mod:`ifcopenshell.api.system`.
+"""
+
+from .. import wrap_usecases
 from .add_group import add_group
 from .assign_group import assign_group
 from .edit_group import edit_group
 from .remove_group import remove_group
 from .unassign_group import unassign_group
 from .update_group_products import update_group_products
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/layer/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/layer/__init__.py
index 03145bf34a..d06b0189d9 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/layer/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/layer/__init__.py
@@ -16,8 +16,20 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage CAD layers
+
+Note that in IFC, elements cannot be assigned to CAD layers. Instead, the
+geometric representation of the element is associated to a layer.
+
+If you want to associated a whole element to a "layer", consider using
+:mod:`ifcopenshell.api.classification`.
+"""
+
+from .. import wrap_usecases
 from .add_layer import add_layer
 from .assign_layer import assign_layer
 from .edit_layer import edit_layer
 from .remove_layer import remove_layer
 from .unassign_layer import unassign_layer
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/library/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/library/__init__.py
index dbb74de3d4..f5984dbfff 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/library/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/library/__init__.py
@@ -16,6 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage references to external libraries
+
+An external library is any system which uses a key to store information. This
+allows you to associate IFC entities with any arbitrary external database, API,
+system, and so on. This is typically useful in smart building systems.
+"""
+
+from .. import wrap_usecases
 from .add_library import add_library
 from .add_reference import add_reference
 from .assign_reference import assign_reference
@@ -24,3 +32,5 @@ from .edit_reference import edit_reference
 from .remove_library import remove_library
 from .remove_reference import remove_reference
 from .unassign_reference import unassign_reference
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/material/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/material/__init__.py
index 2831915f76..a03ccba9aa 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/material/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/material/__init__.py
@@ -16,6 +16,22 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage physical materials (concrete, steel, etc) and their association to
+elements
+
+IFC supports both simple materials and parametric materials (materials that
+have layered thicknesses or cross sectional profiles).
+
+Parametric materials will include parametric constraints on the geometry of
+the element. These API functions do not cover that responsibility. See
+:mod:`ifcopenshell.api.geometry`.
+
+Note that this API only covers physical materials, not visual styles. If you
+want to look at visual styles such as colours, transparency, shading, or
+rendering options, see :mod:`ifcopenshell.api.style`.
+"""
+
+from .. import wrap_usecases
 from .add_constituent import add_constituent
 from .add_layer import add_layer
 from .add_list_item import add_list_item
@@ -40,3 +56,5 @@ from .remove_material_set import remove_material_set
 from .remove_profile import remove_profile
 from .reorder_set_item import reorder_set_item
 from .unassign_material import unassign_material
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/nest/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/nest/__init__.py
index 242e12eb11..162f9c07a2 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/nest/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/nest/__init__.py
@@ -16,7 +16,21 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Nesting is when a component is attached to a host element
+
+Examples include when a faucet is attached using a predrilled hole in a basin,
+or when a modular connection occurs through a connection point. This implies
+that when a host element moves, the child nested components must move as well.
+
+Note that this API is not meant to be used for connection points on
+distribution systems. For that purpose, such as for pipe fittings and
+equipment, please see :mod:`ifcopenshell.api.system`.
+"""
+
+from .. import wrap_usecases
 from .assign_object import assign_object
 from .change_nest import change_nest
 from .reorder_nesting import reorder_nesting
 from .unassign_object import unassign_object
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/owner/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/owner/__init__.py
index 755fa4fc5f..f61689b906 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/owner/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/owner/__init__.py
@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""An element may have an owner, indicating who is responsible, liable, or
+contactable regarding that element
+
+Note that in IFC2X3, element ownership is mandatory and must be addressed prior
+to the creation of any element at all. See :func:`create_owner_history` for
+examples.
+"""
+
+from .. import wrap_usecases
 from .add_actor import add_actor
 from .add_address import add_address
 from .add_application import add_application
@@ -39,3 +48,5 @@ from .remove_person_and_organisation import remove_person_and_organisation
 from .remove_role import remove_role
 from .unassign_actor import unassign_actor
 from .update_owner_history import update_owner_history
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/profile/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/profile/__init__.py
index 7decc6750b..6b4a5a1efd 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/profile/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/profile/__init__.py
@@ -16,8 +16,17 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Handles the definition of cross sectional profiles
+
+Maintaining a clean profile library is important for structural simulations and
+identification of standardised profiles for fabrication and carbon counting.
+"""
+
+from .. import wrap_usecases
 from .add_arbitrary_profile import add_arbitrary_profile
 from .add_arbitrary_profile_with_voids import add_arbitrary_profile_with_voids
 from .add_parameterized_profile import add_parameterized_profile
 from .edit_profile import edit_profile
 from .remove_profile import remove_profile
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/project/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/project/__init__.py
index e9c21fbddd..2641ad8ab8 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/project/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/project/__init__.py
@@ -16,7 +16,20 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create an IFC project
+
+All IFCs must have one, and only one IFC project before any data may be
+associated. If you are starting from scratch, see :func:create_file.
+
+Once a project exists, you may optionally create project libraries and
+associate type assets with it. You may also append assets from other projects
+into your project.
+"""
+
+from .. import wrap_usecases
 from .append_asset import append_asset
 from .assign_declaration import assign_declaration
 from .create_file import create_file
 from .unassign_declaration import unassign_declaration
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/pset/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/pset/__init__.py
index c3e01e30df..dbb4fb84c2 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/pset/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/pset/__init__.py
@@ -16,8 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Property sets and quantity sets let you store simple key value metadata
+associated with elements
+
+This is the simplest and most common way to store information about an element.
+For example, if a door has a fire rating, it is stored as a property.
+"""
+
+from .. import wrap_usecases
 from .add_pset import add_pset
 from .add_qto import add_qto
 from .edit_pset import edit_pset
 from .edit_qto import edit_qto
 from .remove_pset import remove_pset
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/pset_template/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/pset_template/__init__.py
index 1c5963479c..971067d074 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/pset_template/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/pset_template/__init__.py
@@ -16,9 +16,20 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage property templates to standard project property names and data types
+
+To help standardise the naming, data types, and association of properties to
+elements, IFC supports property set templates. buildingSMART provides their own
+built-in ISO-standardised property templates, but governments, companies, and
+individuals may also create their own.
+"""
+
+from .. import wrap_usecases
 from .add_prop_template import add_prop_template
 from .add_pset_template import add_pset_template
 from .edit_prop_template import edit_prop_template
 from .edit_pset_template import edit_pset_template
 from .remove_prop_template import remove_prop_template
 from .remove_pset_template import remove_pset_template
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/resource/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/resource/__init__.py
index 8fcff6a7fc..7d318f8900 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/resource/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/resource/__init__.py
@@ -16,6 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage construction and maintenance resources
+
+Resources include equipment (cranes, etc), labour, material, and products. They
+are typically referenced in construction planning, maintenance schedules, or
+cost items.
+"""
+
+from .. import wrap_usecases
 from .add_resource import add_resource
 from .add_resource_quantity import add_resource_quantity
 from .add_resource_time import add_resource_time
@@ -28,3 +36,5 @@ from .edit_resource_time import edit_resource_time
 from .remove_resource import remove_resource
 from .remove_resource_quantity import remove_resource_quantity
 from .unassign_resource import unassign_resource
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/root/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/root/__init__.py
index 309f87cfff..8845c8e663 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/root/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/root/__init__.py
@@ -16,7 +16,20 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create, copy, or remove physical elements such as walls, doors, slabs, etc
+
+This is one of the most used API modules and should be used any time you want
+to create, remove, copy, or change a physical or spatial element. See
+:func:`create_entity` to get started.
+
+This module should also be used to create types. To then associate types with
+elements, see :mod:`ifcopenshell.api.type`.
+"""
+
+from .. import wrap_usecases
 from .copy_class import copy_class
 from .create_entity import create_entity
 from .reassign_class import reassign_class
 from .remove_product import remove_product
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/sequence/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/sequence/__init__.py
index 90cb5f4922..a901acec9c 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/sequence/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/sequence/__init__.py
@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage work schedules, tasks, calendars, and more for 4D
+
+These are typically used for construction planning, but may also be used in
+managing recurring facility maintenance schedules.
+"""
+
+from .. import wrap_usecases
 from .add_task import add_task
 from .add_task_time import add_task_time
 from .add_time_period import add_time_period
@@ -59,3 +66,5 @@ from .unassign_process import unassign_process
 from .unassign_product import unassign_product
 from .unassign_recurrence_pattern import unassign_recurrence_pattern
 from .unassign_sequence import unassign_sequence
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/spatial/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/spatial/__init__.py
index 22891f5c83..564c91606f 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/spatial/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/spatial/__init__.py
@@ -16,7 +16,16 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Assign spatial relationships such as when an element is in a space
+
+Physical elements (walls, doors, etc) may be contained in or reference spatial
+elements (spaces, storeys, buildings, etc).
+"""
+
+from .. import wrap_usecases
 from .assign_container import assign_container
 from .dereference_structure import dereference_structure
 from .reference_structure import reference_structure
 from .unassign_container import unassign_container
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/structural/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/structural/__init__.py
index 3bdaf8c004..d466add6ce 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/structural/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/structural/__init__.py
@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage analytical properties for structural simulation
+
+This only handles authoring the analytical model, and does not actually perform
+any structural simulation. To perform the simulation, see IFC2CA.
+"""
+
+from .. import wrap_usecases
 from .add_structural_activity import add_structural_activity
 from .add_structural_analysis_model import add_structural_analysis_model
 from .add_structural_boundary_condition import add_structural_boundary_condition
@@ -37,3 +44,5 @@ from .remove_structural_load import remove_structural_load
 from .remove_structural_load_case import remove_structural_load_case
 from .remove_structural_load_group import remove_structural_load_group
 from .unassign_structural_analysis_model import unassign_structural_analysis_model
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/style/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/style/__init__.py
index df9fd47518..e32e13a5b1 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/style/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/style/__init__.py
@@ -16,6 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage visual styles of geometry (colours, transparency, rendering, etc)
+
+Geometry may have visual styles associated with it, including surface styles,
+2D curve styles, text styles, and more. Surface styles are most commonly used
+for simple colouring.
+"""
+
+from .. import wrap_usecases
 from .add_style import add_style
 from .add_surface_style import add_surface_style
 from .add_surface_textures import add_surface_textures
@@ -28,3 +36,5 @@ from .remove_styled_representation import remove_styled_representation
 from .remove_surface_style import remove_surface_style
 from .unassign_material_style import unassign_material_style
 from .unassign_representation_styles import unassign_representation_styles
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/system/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/system/__init__.py
index 14213ca168..0d374c830c 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/system/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/system/__init__.py
@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage distribution systems and port connectivity
+
+Service distribution systems (mechanical, electrical, hydraulic, fire,
+logistical, etc) consist of connected distribution segments, fittings,
+terminals, control equipment, and more. This module handles port connectivity
+and relationships describing distribution flow.
+"""
+
+from .. import wrap_usecases
 from .add_port import add_port
 from .add_system import add_system
 from .assign_flow_control import assign_flow_control
@@ -28,3 +37,5 @@ from .remove_system import remove_system
 from .unassign_flow_control import unassign_flow_control
 from .unassign_port import unassign_port
 from .unassign_system import unassign_system
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/type/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/type/__init__.py
index dddd90a49f..39a523123d 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/type/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/type/__init__.py
@@ -16,7 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage common construction types of physical elements
+
+Almost all constructed elements may be grouped into "types". Types include wall
+types, window types, column types, equipment types, and more.
+
+Using types is critical to the success of any project.
+"""
+
+from .. import wrap_usecases
 from .assign_type import assign_type
 from .get_related_objects import get_related_objects
 from .map_type_representations import map_type_representations
 from .unassign_type import unassign_type
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/unit/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/unit/__init__.py
index 3813724dd7..058e3f2c72 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/unit/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/unit/__init__.py
@@ -16,6 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Define units (length, area, monetary, pressure, etc)
+
+Units can be defined as a default project unit or used specifically for certain
+properties. Units may be especially complex when dealing with services and
+equipment.
+"""
+
+from .. import wrap_usecases
 from .add_context_dependent_unit import add_context_dependent_unit
 from .add_conversion_based_unit import add_conversion_based_unit
 from .add_monetary_unit import add_monetary_unit
@@ -26,3 +34,5 @@ from .edit_monetary_unit import edit_monetary_unit
 from .edit_named_unit import edit_named_unit
 from .remove_unit import remove_unit
 from .unassign_unit import unassign_unit
+
+wrap_usecases(__path__, __name__)
diff --git a/src/ifcopenshell-python/ifcopenshell/api/void/__init__.py b/src/ifcopenshell-python/ifcopenshell/api/void/__init__.py
index 51e0db158b..ae02decb95 100644
--- a/src/ifcopenshell-python/ifcopenshell/api/void/__init__.py
+++ b/src/ifcopenshell-python/ifcopenshell/api/void/__init__.py
@@ -16,7 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Create void relationships between openings and physical elements
+
+An opening is a special element (created using
+:func:`ifcopenshell.api.root.create_entity`) that may then be used to create
+voids in other elements (such as walls and slabs). These voids may then be
+filled with doors, trapdoors, skylights, and so on.
+"""
+
+from .. import wrap_usecases
 from .add_filling import add_filling
 from .add_opening import add_opening
 from .remove_filling import remove_filling
 from .remove_opening import remove_opening
+
+wrap_usecases(__path__, __name__)