DOC: Expand comment for `get_clear_loop` and sprinkle dealloc+nulling

3 files changed, 16 insertions, 6 deletions

diff --git a/numpy/core/src/multiarray/dtype_traversal.c b/numpy/core/src/multiarray/dtype_traversal.c
index 6a1d31b8f..0725d2097 100644
--- a/numpy/core/src/multiarray/dtype_traversal.c
+++ b/numpy/core/src/multiarray/dtype_traversal.c
@@ -5,7 +5,7 @@
  *
  * As of writing, it is only used for CLEARing, which means mainly
  * Python object DECREF/dealloc followed by NULL'ing the data
- * (to support double clearing on errors).
+ * (to support double clearing and ensure data is again in a usable state).
  * However, memory initialization and traverse follows similar
  * protocols (although traversal needs additional arguments).
  */
@@ -68,7 +68,10 @@ get_clear_function(
 }
 
 /*
- * Helper to set up a strided loop used for clearing.
+ * Helper to set up a strided loop used for clearing.  Clearing means
+ * deallocating any references (e.g. via Py_DECREF) and resetting the data
+ * back into a usable/initialized state (e.g. by NULLing any references).
+ *
  * The function will error when called on a dtype which does not have
  * references (and thus the get_clear_loop slot NULL).
  * Note that old-style user-dtypes use the "void" version.
diff --git a/numpy/core/src/multiarray/dtype_traversal.h b/numpy/core/src/multiarray/dtype_traversal.h
index d574657fb..5bf983a78 100644
--- a/numpy/core/src/multiarray/dtype_traversal.h
+++ b/numpy/core/src/multiarray/dtype_traversal.h
@@ -27,7 +27,7 @@ typedef int (get_traverse_loop_function)(
         NPY_ARRAYMETHOD_FLAGS *flags);
 
 
-/* NumPy DType clear implementations */
+/* NumPy DType clear (object DECREF + NULLing) implementations */
 
 NPY_NO_EXPORT int
 npy_get_clear_object_strided_loop(
diff --git a/numpy/core/src/multiarray/dtypemeta.h b/numpy/core/src/multiarray/dtypemeta.h
index 3acbcb561..5bff5fdb1 100644
--- a/numpy/core/src/multiarray/dtypemeta.h
+++ b/numpy/core/src/multiarray/dtypemeta.h
@@ -35,9 +35,16 @@ typedef struct {
      */
     PyArrayMethodObject *within_dtype_castingimpl;
     /*
-     * Implementation which clears a dtype or NULL.  If not given, setting
-     * NPY_ITEM_REFCOUNT on the dtype is invalid.  Note that NPY_ITEM_REFCOUNT
-     * may inidicate references that are not Python objects.
+     * Either NULL or fetches a clearing function.  Clearing means deallocating
+     * any referenced data and setting it to a safe state.  For Python objects
+     * this means using `Py_CLEAR` which is equivalent to `Py_DECREF` and
+     * setting the `PyObject *` to NULL.
+     * After the clear, the data must be fillable via cast/copy and calling
+     * clear a second time must be safe.
+     * If the DType class does not implement `get_clear_loop` setting
+     * NPY_ITEM_REFCOUNT on its dtype instances is invalid.  Note that it is
+     * acceptable for  NPY_ITEM_REFCOUNT to inidicate references that are not
+     * Python objects.
      */
     get_traverse_loop_function *get_clear_loop;
     /*