DOC: Document the internal workings of PY_ARRAY_UNIQUE_SYMBOL

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 1291dc93c..b00919fae 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -3063,6 +3063,24 @@ the C-API is needed then some additional steps must be taken.
     header file as long as you make sure that NO_IMPORT_ARRAY is
     #defined before #including that file.
 
+    Internally, these #defines work as follows:
+
+        * If neither is defined, the C-API is declared to be
+          :c:type:`static void**`, so it is only visible within the
+          compilation unit that #includes numpy/arrayobject.h.
+        * If :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, but
+          :c:macro:`NO_IMPORT_ARRAY` is not, the C-API is declared to
+          be :c:type:`void**`, so that it will also be visible to other
+          compilation units.
+        * If :c:macro:`NO_IMPORT_ARRAY` is #defined, regardless of
+          whether :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is, the C-API is
+          declared to be :c:type:`extern void**`, so it is expected to
+          be defined in another compilation unit.
+        * Whenever :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, it
+          also changes the name of the variable holding the C-API, which
+          defaults to :c:data:`PyArray_API`, to whatever the macro is
+          #defined to.
+
 Checking the API Version
 ^^^^^^^^^^^^^^^^^^^^^^^^