📝 Add docstrings to fea-enum-prefix-removal

numbast/src/numbast/static/enum.py

@@ -32,6 +32,16 @@ class {enum_name}(IntEnum):
     def __init__(
         self, decl: Enum, enum_prefix_removal: list[str] | None = None
     ):
+        """
+        Initialize the renderer for a single C++ enum and derive its Python enum name.
+
+        Parameters:
+            decl (Enum): The parsed C++ enum declaration to render.
+            enum_prefix_removal (list[str] | None): Prefix strings to remove from the C++ enum and enumerator names when deriving Python identifiers; empty list if None.
+
+        Description:
+            Stores the declaration and prefix-removal configuration, computes the Python enum name from the C++ name using the provided prefixes, and appends that Python name to the renderer's symbol list.
+        """
         self._decl = decl
         self._enum_prefix_removal = enum_prefix_removal or []
 
@@ -42,6 +52,15 @@ def __init__(
         self._enum_symbols.append(self._enum_name)
 
     def _render(self):
+        """
+        Render the stored C++ enum declaration into a Python IntEnum class and store the generated source.
+
+        This method:
+        - Ensures required imports for `IntEnum`, `IntEnumMember`, and `int64` are added to the renderer's import set.
+        - Registers the mapping from the original C++ enum name to the computed Python enum name.
+        - Applies configured prefix removal to each enumerator, formats enumerator lines, and assembles the final class text.
+        - Writes the resulting Python class source into `self._python_rendered`.
+        """
         self.Imports.add("from enum import IntEnum")
         self.Imports.add("from numba.types import IntEnumMember")
         self.Imports.add("from numba.types import int64")
@@ -73,14 +92,31 @@ class StaticEnumsRenderer(BaseRenderer):
     def __init__(
         self, decls: list[Enum], enum_prefix_removal: list[str] | None = None
     ):
+        """
+        Initialize the renderer for a collection of C++ enum declarations.
+
+        Parameters:
+            decls (list[Enum]): The list of enum declarations to render.
+            enum_prefix_removal (list[str] | None): Optional list of prefixes to remove from enum and enumerator names when generating Python bindings; defaults to an empty list.
+
+        Notes:
+            Initializes internal state and a list to accumulate per-enum rendered Python strings.
+        """
         super().__init__(decls)
         self._decls = decls
         self._enum_prefix_removal = enum_prefix_removal or []
 
         self._python_rendered: list[str] = []
 
     def _render(self, with_imports):
-        """Render python bindings for enums."""
+        """
+        Render all stored C++ enum declarations into Python binding source and store the result on the renderer instance.
+
+        This populates self._python_rendered with each enum's rendered string and assembles the combined output into self._python_str. If with_imports is True, the module import block is included at the top of the assembled output.
+
+        Parameters:
+                with_imports (bool): If True, prepend the rendered import block to the assembled Python output.
+        """
         self._python_str = ""
 
         for decl in self._decls:

numbast/src/numbast/static/function.py

@@ -412,6 +412,18 @@ def __init__(
         use_cooperative: bool,
         function_prefix_removal: list[str] = [],
     ):
+        """
+        Initialize the non-operator function renderer, compute the Python-facing function name by removing configured prefixes, and update tracked function symbols accordingly.
+
+        Parameters:
+            decl (Function): The parsed function declaration to render.
+            header_path (str): Path to the C++ header containing the declaration.
+            use_cooperative (bool): Whether the function requires cooperative launch support.
+            function_prefix_removal (list[str]): List of prefixes to remove from the original function name to produce the Python-visible name.
+
+        Notes:
+            This initializer replaces the original C++ name in the renderer's tracked function symbols with the computed Python name.
+        """
         super().__init__(decl, header_path, use_cooperative)
         self._python_func_name = _apply_prefix_removal(
             decl.name, function_prefix_removal
@@ -426,7 +438,12 @@ def __init__(
 
     @property
     def func_name_python(self):
-        """The name of the function in python with prefix removal applied."""
+        """
+        Python-visible function name after applying configured prefix removal.
+
+        Returns:
+            str: The Python-exposed function name with any configured prefixes removed.
+        """
         return self._python_func_name
 
     def _render_python_api(self):

numbast/src/numbast/static/renderer.py

@@ -87,6 +87,15 @@ def reset(self):
     """List of new enum handles to expose."""
 
     def __init__(self, decl):
+        """
+        Initialize the BaseRenderer with a declaration and ensure required base imports are registered.
+
+        Parameters:
+            decl: The parsed declaration object the renderer will use to produce code.
+
+        Notes:
+            This constructor records "import numba" and "import io" in the class-level Imports set as part of instance initialization.
+        """
         self.Imports.add("import numba")
         self.Imports.add("import io")
         self._decl = decl
@@ -123,6 +132,13 @@ def render_as_str(
 
 
 def clear_base_renderer_cache():
+    """
+    Clear all class-level caches and exposed-symbol lists on BaseRenderer.
+
+    This resets shared renderer state by removing all entries from the following BaseRenderer attributes:
+    `Imports`, `Imported_VectorTypes`, `Includes`, `ShimFunctions`, `_imported_numba_types`,
+    `_nbtype_symbols`, `_record_symbols`, `_function_symbols`, and `_enum_symbols`.
+    """
     BaseRenderer.Imports.clear()
     BaseRenderer.Imported_VectorTypes.clear()
     BaseRenderer.Includes.clear()
@@ -137,6 +153,17 @@ def clear_base_renderer_cache():
 def get_reproducible_info(
     config_rel_path: str, cmd: str, sbg_params: dict[str, str]
 ) -> str:
+    """
+    Produce a reproducible information header composed of commented lines documenting versions, the generation command, generator parameters, and the config path.
+
+    Parameters:
+        config_rel_path (str): Path to the generator configuration file relative to the generated binding file.
+        cmd (str): The command line used to invoke the generation.
+        sbg_params (dict[str, str]): Static binding generator parameters to record.
+
+    Returns:
+        str: A multi-line string where each line is prefixed with "# " and the block ends with a single trailing newline.
+    """
     info = [
         f"Ast_canopy version: {ast_canopy_ver}",
         f"Numbast version: {numbast_ver}",
@@ -238,6 +265,12 @@ def _get_record_symbols() -> str:
 
 
 def _get_function_symbols() -> str:
+    """
+    Render a Python code block that defines the _FUNCTION_SYMBOLS list from BaseRenderer._function_symbols.
+
+    Returns:
+        code (str): A string containing a Python assignment that defines `_FUNCTION_SYMBOLS` as a list of symbol names quoted and comma-separated.
+    """
     template = """
 _FUNCTION_SYMBOLS = [{function_symbols}]
 """
@@ -250,6 +283,14 @@ def _get_function_symbols() -> str:
 
 
 def _get_enum_symbols() -> str:
+    """
+    Generate a Python source snippet that defines the `_ENUM_SYMBOLS` list from BaseRenderer._enum_symbols.
+
+    The returned string is a ready-to-insert code block where each enum name is quoted and placed into a Python list assigned to `_ENUM_SYMBOLS`.
+
+    Returns:
+        A string containing Python code that assigns `_ENUM_SYMBOLS` to a list of quoted enum symbol names (e.g., `_ENUM_SYMBOLS = ["A","B"]`).
+    """
     template = """
 _ENUM_SYMBOLS = [{enum_symbols}]
 """
@@ -262,12 +303,12 @@ def _get_enum_symbols() -> str:
 
 
 def get_all_exposed_symbols() -> str:
-    """Return the definition of all exposed symbols via `__all__`.
+    """
+    Produce the code block that defines and exposes all symbol name lists and the module __all__.
 
-    A generated binding module exposes the following symbols:
-    - Name of a record, corresponds to the handle of the python object
-    - Name of the record type instance in Numba, corresponds to the record's numba type
-    - Name of a function, corresponds to the handle of the python object
+    Returns:
+        A string containing Python code that defines `_NBTYPE_SYMBOLS`, `_RECORD_SYMBOLS`, `_FUNCTION_SYMBOLS`, `_ENUM_SYMBOLS`
+        and an `__all__` list that is the concatenation of those symbol lists.
     """
 
     nbtype_symbols = _get_nbtype_symbols()