DOC: warn against using zero-filling loop with a previously allocated array

2 files changed, 6 insertions, 0 deletions

diff --git a/numpy/core/src/multiarray/dtype_traversal.c b/numpy/core/src/multiarray/dtype_traversal.c
index 39b30ad3b..769c2e015 100644
--- a/numpy/core/src/multiarray/dtype_traversal.c
+++ b/numpy/core/src/multiarray/dtype_traversal.c
@@ -135,6 +135,7 @@ fill_zero_object_strided_loop(
     PyObject *zero = PyLong_FromLong(0);
     while (size--) {
         Py_INCREF(zero);
+        // assumes `data` doesn't have a pre-existing object inside it
         memcpy(data, &zero, sizeof(zero));
         data += stride;
     }
diff --git a/numpy/core/src/multiarray/dtypemeta.h b/numpy/core/src/multiarray/dtypemeta.h
index 8baf5628a..6dbfd1549 100644
--- a/numpy/core/src/multiarray/dtypemeta.h
+++ b/numpy/core/src/multiarray/dtypemeta.h
@@ -51,6 +51,11 @@ typedef struct {
        called to fill the buffer. For the best performance, avoid using this
        function if a zero-filled array buffer allocated with calloc makes sense
        for the dtype.
+
+       Note that this is currently used only for zero-filling a newly allocated
+       array. While it can be used to zero-fill an already-filled buffer, that
+       will not work correctly for arrays holding references. If you need to do
+       that, clear the array first.
     */
     get_traverse_loop_function *get_fill_zero_loop;
     /*