NVIDIA
diff --git a/‎numbast/src/numbast/args.py‎
Lines changed: 16 additions & 17 deletions b/‎numbast/src/numbast/args.py‎
Lines changed: 16 additions & 17 deletions
diff --git a/‎numbast/src/numbast/callconv.py‎
Lines changed: 30 additions & 0 deletions b/‎numbast/src/numbast/callconv.py‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎numbast/src/numbast/class_template.py‎
Lines changed: 61 additions & 45 deletions b/‎numbast/src/numbast/class_template.py‎
Lines changed: 61 additions & 45 deletions
diff --git a/‎numbast/src/numbast/function.py‎
Lines changed: 47 additions & 46 deletions b/‎numbast/src/numbast/function.py‎
Lines changed: 47 additions & 46 deletions
@@ -13,23 +13,22 @@ def prepare_ir_types(
     pass_ptr_mask: list[bool] | None = None,
 ) -> list[ir.Type]:
     """
-    Prepare IR types for passing arguments via pointers in function calls.
-
-    This utility wraps each argument type in a PointerType to enable
-    the call convention used by FunctionCallConv, where arguments are
-    passed by reference.
-
-    Parameters
-    ----------
-    context : context object
-        The compilation context providing the get_value_type method.
-    argtys : list[ir.Type]
-        List of LLVM IR types representing function arguments.
-
-    Returns
-    -------
-    list[ir.Type]
-        List of pointer types wrapping the value types of each argument.
+    Prepare LLVM IR types for passing function arguments by reference.
+
+    Given a list of argument IR types, return a parallel list of IR types suitable for an ABI that passes arguments by pointer. For each argument, the context's get_value_type() is used to obtain the value type; if the corresponding entry in pass_ptr_mask is True and that value type is already an ir.PointerType, that pointer type is preserved, otherwise the value type is wrapped in an ir.PointerType.
+
+    Parameters:
+        context (CUDATargetContext): Compilation context used to obtain the value type via get_value_type().
+        argtys (list[ir.Type]): Argument IR types to prepare.
+        pass_ptr_mask (list[bool] | None): Optional mask the same length as argtys indicating per-argument behavior.
+            If None, all entries are treated as False. When True for an argument and the value type is an ir.PointerType,
+            the pointer type is passed through unchanged.
+
+    Returns:
+        list[ir.Type]: Prepared IR types where each entry is either a pointer-to-value or an existing pointer type preserved per pass_ptr_mask.
+
+    Raises:
+        ValueError: If pass_ptr_mask is provided and its length does not match len(argtys).
     """
     if pass_ptr_mask is None:
         pass_ptr_mask = [False] * len(argtys)
 
@@ -53,6 +53,18 @@ def __init__(
         out_return_types: list[types.Type] | None = None,
         cxx_return_type: types.Type | None = None,
     ):
+        """
+        Initialize a FunctionCallConv with shim information and optional ABI/intent hints.
+
+        Parameters:
+            itanium_mangled_name (str): The Itanium-mangled C++ function name used to derive the shim name.
+            shim_writer (object): Writer used to emit the shim code when required.
+            shim_code (str): LLVM/IR code template for the shim.
+            arg_is_ref (list[bool] | None): Per-argument mask indicating whether an argument should be passed as a pointer (True) or by value (False). If None, pointer-passing is determined later or defaults to all False.
+            intent_plan (IntentPlan | None): Optional plan describing visible parameter indices, which parameters should be passed as pointers, and which parameters are out-returns; when present it drives argument mapping and out-return handling.
+            out_return_types (list[types.Type] | None): Types of the out-return values in the order declared by the IntentPlan; required when the intent_plan defines out-return indices.
+            cxx_return_type (types.Type | None): The C++ ABI return type to use for allocating/shimming the return slot; if None, the signature's return type is used.
+        """
         super().__init__(itanium_mangled_name, shim_writer, shim_code)
         self._arg_is_ref = list(arg_is_ref) if arg_is_ref is not None else None
         self._intent_plan = intent_plan
@@ -64,6 +76,24 @@ def __init__(
     def _lower_impl(self, builder, context, sig, args):
         # Numba-visible return type may differ from the underlying C++ return type
         # when out_return parameters are enabled (tuple returns, etc.).
+        """
+        Lower the configured call into a shim invocation, preparing return and argument pointers according to arg_is_ref or an IntentPlan and materializing the final Numba-visible return value.
+
+        Parameters:
+            builder: LLVM IR builder used to emit allocations, stores, and calls.
+            context: Compilation context used to map numba types to LLVM value types and to construct tuple return values.
+            sig: Numba function signature describing the visible parameter and return types.
+            args: Sequence of LLVM IR values corresponding to the visible signature parameters.
+
+        Returns:
+            The loaded return value(s) according to the signature and intent plan:
+            - `None` if the effective C++ return type is void and no out-return values are present.
+            - A single LLVM value for a single visible return.
+            - A tuple object constructed via `context.make_tuple` when the visible return type is a tuple; the tuple contains the C++ return (if non-void) followed by any out-return values.
+
+        Raises:
+            ValueError: if the provided IntentPlan does not align with `sig` (mismatched visible_param_indices or pass_ptr_mask), if `out_return_types` are required but missing or length-mismatched, or if a non-tuple visible return is expected but multiple return values are produced.
+        """
         cxx_return_type = (
             self._cxx_return_type
             if self._cxx_return_type is not None
 
@@ -85,27 +85,17 @@ def bind_cxx_struct_ctor(
     s_type_ref: nbtypes.TypeRef,
     shim_writer: ShimWriterBase,
 ) -> Optional[list]:
-    """Create bindings for a C++ struct constructor and return its argument types.
+    """
+    Bind a C++ struct constructor into Numba and return the constructor's argument types.
 
-    Parameters
-    ----------
+    Parameters:
+        ctor (StructMethod): The C++ constructor declaration to bind.
+        struct_name (str): The name of the C++ struct being bound.
+        s_type_ref (numba.types.TypeRef): The Numba TypeRef that represents the struct instantiation.
+        shim_writer (ShimWriterBase): Writer used to emit the shim function for the constructor.
 
-    ctor : StructMethod
-        Constructor declaration of struct in CXX
-    struct_name : str
-        The name of the struct from which this constructor belongs to
-    s_type : numba.types.Type
-        The Numba type of the struct
-    S : object
-        The Python API of the struct
-    shim_writer : ShimWriterBase
-        The shim writer to write the shim layer code.
-
-    Returns
-    -------
-    list of argument types, optional
-        If the constructor is a move constructor, return ``None``. Otherwise,
-        return the list of argument types.
+    Returns:
+        list: A list of Numba argument types for the constructor, or `None` if the constructor is a move constructor.
     """
 
     if ctor.is_move_constructor:
@@ -142,6 +132,14 @@ def bind_cxx_struct_ctor(
     def ctor_impl(context, builder, sig, args):
         # `numba_typeref_ctor` includes the typeref as the first argument; the
         # generated shim expects only the actual constructor params.
+        """
+        Lowering implementation for a template-type constructor that delegates to the constructor call-convention with the instance type and actual constructor parameters.
+
+        This function builds a constructor signature whose first parameter is the concrete instance type and invokes the prepared FunctionCallConv, passing the original args with the leading typeref argument removed.
+
+        Returns:
+            The value produced by the constructor call-convention (the constructed instance).
+        """
         ctor_sig = nb_signature(s_type_ref.instance_type, *param_types)
         return ctor_cc(builder, context, ctor_sig, args[1:])
 
@@ -292,6 +290,23 @@ def bind_cxx_struct_regular_method(
     *,
     arg_intent: dict | None = None,
 ) -> nb_signature:
+    """
+    Bind a single C++ struct regular method to a Numba-callable signature and register its lowering.
+
+    Parameters:
+        struct_decl (ClassTemplateSpecialization): Parsed C++ class template specialization for the method's declaring type.
+        method_decl (StructMethod): Parsed method declaration describing name, parameters, and C++ return type.
+        s_type (nbtypes.Type): The Numba type representing the struct instance (receiver) used in the generated signature.
+        shim_writer (ShimWriterBase): Writer used to emit the native shim invoked by the lowering.
+        arg_intent (dict | None, optional): Optional mapping of "TypeName.methodName" -> intent overrides. When provided,
+            visible parameters, pointer-passing intents, and out-returns are derived from the overrides and may cause the
+            resulting Numba signature and return type to include out-return values or pointer-wrapped parameters.
+
+    Returns:
+        nb_signature: The Numba signature for the bound method (including the receiver as `recvr`). The signature's return
+        type reflects any out-return promotion caused by `arg_intent` overrides; otherwise it matches the method's C++
+        return type.
+    """
     cxx_return_type = to_numba_type(
         method_decl.return_type.unqualified_non_ref_type_name
     )
@@ -400,11 +415,16 @@ def bind_cxx_struct_regular_methods(
     arg_intent: dict | None = None,
 ) -> dict[str, ConcreteTemplate]:
     """
+    Collect concrete typing templates for all regular member functions of a C++ class template specialization.
 
-    Return
-    ------
+    Parameters:
+        struct_decl (ClassTemplateSpecialization): The parsed C++ class specialization declaration.
+        s_type (nbtypes.Type): The Numba type representing the instantiated struct.
+        shim_writer (ShimWriterBase): Writer used to emit shim code for bound methods.
+        arg_intent (dict | None): Optional mapping of argument-intent overrides (keyed by method or parameter as consumed by the per-method binder); forwarded to individual method bindings.
 
-    Mapping from function names to list of signatures.
+    Returns:
+        dict[str, ConcreteTemplate]: Mapping from method name to a ConcreteTemplate whose cases are the collected Numba signatures for that method's overloads.
     """
 
     method_overloads: dict[str, list[nb_signature]] = defaultdict(list)
@@ -804,29 +824,25 @@ def bind_cxx_class_template_specialization(
     arg_intent: dict | None = None,
 ) -> object:
     """
-    Create bindings for a C++ struct.
-
-    Parameters
-    ----------
-    shim_writer : ShimWriterBase
-        The shim writer to write the shim layer code.
-    struct_decl : Struct
-        Declaration of the struct type in CXX
-    parent_type : nbtypes.Type, optional
-        Parent type of the Python API, by default nbtypes.Type
-    data_model : type, optional
-        Data model for the struct, by default StructModel
-    aliases : dict[str, list[str]], optional
-        Mappings from the name of the struct to a list of aliases.
-        For example in C++: typedef A B; typedef A C; then
-        aliases = {"A": ["B", "C"]}
-
-    Returns
-    -------
-    S : object
-        The Python API of the struct.
-    shim: str
-        The generated shim layer code for struct methods.
+    Bind a C++ class template specialization into Numba and return the corresponding Numba instance type.
+
+    This registers the C++ name-to-Numba-type mapping, installs a StructModel for the instantiated type, registers attribute and method typing templates, and binds constructors so the specialization can be used from Numba.
+
+    Parameters:
+        shim_writer: ShimWriterBase
+            Utility used to emit shim-layer code for bound methods.
+        struct_decl: ClassTemplateSpecialization
+            Parsed C++ class template specialization declaration to bind.
+        instance_type_ref: nbtypes.Type
+            The Numba TypeRef representing the instantiated template; its .instance_type is the returned type.
+        aliases: dict[str, list[str]], optional
+            Optional name aliases for the C++ type (e.g., typedefs) to register to the same Numba type.
+        arg_intent: dict | None, optional
+            Optional per-argument intent overrides to influence method parameter/return typing.
+
+    Returns:
+        nbtypes.Type
+            The Numba instance type for the bound class template specialization (instance_type_ref.instance_type).
     """
 
     s_type = instance_type_ref.instance_type
 
@@ -48,20 +48,15 @@ def bind_cxx_operator_overload_function(
     *,
     arg_intent: dict | None = None,
 ) -> object:
-    """Create bindings for a C++ operator-overload function.
-
-    Parameters
-    ----------
-    shim_writer : ShimWriter
-        The shim writer to write the generated shim layer code.
+    """
+    Create a Numba-callable binding for a C++ operator-overload function.
 
-    func_decl : Function
-        The declaration of the function in C++.
+    Parameters:
+        func_decl (Function): C++ function declaration to bind.
+        arg_intent (dict | None): Optional mapping that customizes argument intent (e.g., which reference parameters are treated as input, output, or inout). When provided, intent controls visible parameter/pointer treatment and out-return composition.
 
-    Returns
-    -------
-    shim_call : object
-        The Numba-CUDA-callable Python API for the function.
+    Returns:
+        FunctionCallConv | None: A callable wrapper used during lowering that performs the bound call, or `None` when the operator is unsupported (e.g., copy assignment operators).
     """
     if func_decl.is_copy_assignment_operator():
         # copy assignment operator, do not support in Numba / Python, skip
@@ -110,6 +105,18 @@ class op_decl(ConcreteTemplate):
 
     @lower(py_op, *param_types)
     def impl(context, builder, sig, args):
+        """
+        Delegate lowering to the captured FunctionCallConv instance `func_cc`.
+
+        Parameters:
+            context: Numba lowering context used during compilation.
+            builder: LLVM IR builder used to emit instructions.
+            sig: The function signature being lowered.
+            args: Sequence of lowered argument values passed to the call.
+
+        Returns:
+            The lowered native value(s) produced by `func_cc`.
+        """
         return func_cc(builder, context, sig, args)
 
     return func_cc
@@ -123,27 +130,28 @@ def bind_cxx_non_operator_function(
     *,
     arg_intent: dict | None = None,
 ) -> object:
-    """Create bindings for a C++ non-operator function.
+    """
+    Create a Python-callable binding for a C++ non-operator function.
+
+    Optionally uses an arg_intent override to control which C++ reference parameters are exposed as pointer parameters or returned as out-returns; when no overrides are provided, reference parameters are treated as input-only values.
 
     Parameters
     ----------
     shim_writer : ShimWriter
-        The shim writer to write the generated shim layer code.
-
+        Writer used to emit the generated shim layer code.
     func_decl : Function
-        The declaration of the function in C++.
-
+        C++ function declaration to bind.
     skip_prefix : str | None
-        Skip functions with this prefix. Has no effect if None or empty.
-
+        If provided, skip functions whose names start with this prefix.
     exclude : set[str]
-        A set of function names to exclude.
-
+        Set of function names to exclude from binding.
+    arg_intent : dict | None, optional
+        Optional per-function intent overrides that specify visibility and in/out semantics for reference parameters.
 
     Returns
     -------
-    func : object
-        The Python-callable API for the function.
+    object
+        The Python-callable function object registered for the bound C++ function, or `None` if the function is skipped.
     """
     global overload_registry
 
@@ -262,29 +270,22 @@ def bind_cxx_function(
     *,
     arg_intent: dict | None = None,
 ) -> object:
-    """Create bindings for a C++ function.
-
-    Parameters
-    ----------
-    shim_writer : ShimWriter
-        The shim writer to write the generated shim layer code.
-
-    func_decl : Function
-        Declaration of the function in CXX
-
-    skip_prefix : str | None
-        Skip functions with this prefix. Has no effect if None or empty.
-
-    skip_non_device : bool
-        Skip non device functions. Default to True.
-
-    exclude : set[str]
-        A set of function names to exclude. Default to empty set.
-
-    Returns
-    -------
-    func : object
-        The Numba-CUDA-callable Python API for the function.
+    """
+    Create Python bindings for a C++ function.
+
+    Parameters:
+        shim_writer (ShimWriter): Writer that emits the generated C/C++ shim code.
+        func_decl (Function): C++ function declaration to bind.
+        skip_prefix (str | None): If provided, skip functions whose names start with this prefix.
+        skip_non_device (bool): If True, skip functions not marked for device or host_device execution.
+        exclude (set[str]): Names of functions to exclude from binding.
+        arg_intent (dict | None): Optional explicit intent overrides that control which C++ reference
+            parameters are exposed as inputs, outputs, or inout pointers and which parameters are
+            promoted to out-returns.
+
+    Returns:
+        object or None: The Numba-CUDA-callable Python binding object for the function, or `None`
+        if the function is skipped or not exposed.
     """
 
     if skip_non_device and func_decl.exec_space not in {