Add structref as a mutable struct that is pass-by-ref

docs/source/developer/repomap.rst

@@ -82,7 +82,7 @@ These define aspects of the public Numba interface.
   regular functions on the CPU
 - :ghfile:`numba/core/extending.py` - Public decorators for extending Numba
   (``overload``, ``intrinsic``, etc)
-  - :ghfile:`numba/core/structref.py` - Public API for defining mutable struct
+  - :ghfile:`numba/core/structref.py` - Public API for defining a mutable struct
 - :ghfile:`numba/core/ccallback.py` - ``@cfunc`` decorator for compiling
   functions to a fixed C signature.  Used to make callbacks.
 - :ghfile:`numba/np/ufunc/decorators.py` - ufunc/gufunc compilation

numba/core/types/containers.py

@@ -722,7 +722,7 @@ def __init__(self, fields):
         Parameters
         ----------
         fields : Sequence
-            A sequence of field description, which is a 2-tuple-like object
+            A sequence of field descriptions, which is a 2-tuple-like object
             containing `(name, type)`, where `name` is a `str` for the field
             name, and `type` is a numba type for the field type.
         """
@@ -733,7 +733,7 @@ def __init__(self, fields):
 
     @property
     def field_dict(self):
-        """Return a immutable mapping for the field names and their
+        """Return an immutable mapping for the field names and their
         corresponding types.
         """
         return MappingProxyType(dict(self._fields))

numba/core/structref.py → numba/experimental/structref.py

@@ -29,7 +29,7 @@ def __init__(self, context, builder, struct_type):
         self.struct_type = struct_type
 
     def new_struct_ref(self, mi):
-        """Turn a MemInfo of `StructRefPayload` to a `StructRef`
+        """Encapsulate the MemInfo from a `StructRefPayload` in a `StructRef`
         """
         context = self.context
         builder = self.builder
@@ -258,7 +258,7 @@ def register(struct_type):
         class MyStruct(numba.core.types.StructRef):
             ...  # the simplest subclass can be empty
 
-        numba.core.structref.register(MyStruct)
+        numba.experimental.structref.register(MyStruct)
 
     """
     if struct_type is types.StructRef:
@@ -360,6 +360,6 @@ def ctor(*args):
     def _numba_type_(self):
         """Returns the Numba type instance for this structref instance.
 
-        Subclass should NOT override.
+        Subclasses should NOT override.
         """
         return self._type

numba/tests/test_struct_ref.py

@@ -16,7 +16,7 @@
 @structref.register
 class MySimplerStructType(types.StructRef):
     """
-    Test associated to this type represent the lowest level uses of structref.
+    Test associated with this type represent the lowest level uses of structref.
     """
     pass
 
@@ -64,7 +64,7 @@ class MyStructType(types.StructRef):
 
 # Call to define_proxy is needed to register the use of `MyStruct` as a
 # PyObject proxy for creating a Numba-allocated structref.
-# The `MyStruct` class and then be used in both jit-code and interpreted-code.
+# The `MyStruct` class can then be used in both jit-code and interpreted-code.
 structref.define_proxy(
     MyStruct,
     MyStructType,