Merge pull request #13892 from kritisingh1/refactor-3

DOC : Refactor Array API documentation -- Array Structure and Data Access

2 files changed, 81 insertions, 69 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 39f936414..3d6246baa 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -20,27 +20,44 @@ Array API
 Array structure and data access
 -------------------------------
 
-These macros all access the :c:type:`PyArrayObject` structure members. The input
-argument, arr, can be any :c:type:`PyObject *<PyObject>` that is directly interpretable
-as a :c:type:`PyArrayObject *` (any instance of the :c:data:`PyArray_Type` and its
-sub-types).
+These macros access the :c:type:`PyArrayObject` structure members and are
+defined in ``ndarraytypes.h``. The input argument, *arr*, can be any
+:c:type:`PyObject *<PyObject>` that is directly interpretable as a
+:c:type:`PyArrayObject *` (any instance of the :c:data:`PyArray_Type`
+and itssub-types).
 
 .. c:function:: int PyArray_NDIM(PyArrayObject *arr)
 
     The number of dimensions in the array.
 
-.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
+.. c:function:: int PyArray_FLAGS(PyArrayObject* arr)
 
-    Returns a pointer to the dimensions/shape of the array. The
-    number of elements matches the number of dimensions
-    of the array. Can return ``NULL`` for 0-dimensional arrays.
+    Returns an integer representing the :ref:`array-flags<array-flags>`.
 
-.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
+.. c:function:: int PyArray_TYPE(PyArrayObject* arr)
+
+    Return the (builtin) typenumber for the elements of this array.
+
+.. c:function:: int PyArray_SETITEM( \
+        PyArrayObject* arr, void* itemptr, PyObject* obj)
+
+    Convert obj and place it in the ndarray, *arr*, at the place
+    pointed to by itemptr. Return -1 if an error occurs or 0 on
+    success.
+
+.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
 
     .. versionadded:: 1.7
 
-    A synonym for PyArray_DIMS, named to be consistent with the
-    'shape' usage within Python.
+    Enables the specified array flags. This function does no validation,
+    and assumes that you know what you're doing.
+
+.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
+
+    .. versionadded:: 1.7
+
+    Clears the specified array flags. This function does no validation,
+    and assumes that you know what you're doing.
 
 .. c:function:: void *PyArray_DATA(PyArrayObject *arr)
 
@@ -53,6 +70,19 @@ sub-types).
     array then be sure you understand how to access the data in the
     array to avoid memory and/or alignment problems.
 
+.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
+
+    Returns a pointer to the dimensions/shape of the array. The
+    number of elements matches the number of dimensions
+    of the array. Can return ``NULL`` for 0-dimensional arrays.
+
+.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
+
+    .. versionadded:: 1.7
+
+    A synonym for :c:func:`PyArray_DIMS`, named to be consistent with the
+    `shape <numpy.ndarray.shape>` usage within Python.
+
 .. c:function:: npy_intp *PyArray_STRIDES(PyArrayObject* arr)
 
     Returns a pointer to the strides of the array. The
@@ -67,6 +97,27 @@ sub-types).
 
     Return the stride in the *n* :math:`^{\textrm{th}}` dimension.
 
+.. c:function:: npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)
+
+    Return the itemsize for the elements of this array.
+
+    Note that, in the old API that was deprecated in version 1.7, this function
+    had the return type ``int``.
+
+.. c:function:: npy_intp PyArray_SIZE(PyArrayObject* arr)
+
+    Returns the total size (in number of elements) of the array.
+
+.. c:function:: npy_intp PyArray_Size(PyArrayObject* obj)
+
+    Returns 0 if *obj* is not a sub-class of ndarray. Otherwise,
+    returns the total number of elements in the array. Safer version
+    of :c:func:`PyArray_SIZE` (*obj*).
+
+.. c:function:: npy_intp PyArray_NBYTES(PyArrayObject* arr)
+
+    Returns the total number of bytes consumed by the array.
+
 .. c:function:: PyObject *PyArray_BASE(PyArrayObject* arr)
 
     This returns the base object of the array. In most cases, this
@@ -93,60 +144,12 @@ sub-types).
     A synonym for PyArray_DESCR, named to be consistent with the
     'dtype' usage within Python.
 
-.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
-
-    .. versionadded:: 1.7
-
-    Enables the specified array flags. This function does no validation,
-    and assumes that you know what you're doing.
-
-.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
-
-    .. versionadded:: 1.7
-
-    Clears the specified array flags. This function does no validation,
-    and assumes that you know what you're doing.
-
-.. c:function:: int PyArray_FLAGS(PyArrayObject* arr)
-
-.. c:function:: npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)
-
-    Return the itemsize for the elements of this array.
-
-    Note that, in the old API that was deprecated in version 1.7, this function
-    had the return type ``int``.
-
-.. c:function:: int PyArray_TYPE(PyArrayObject* arr)
-
-    Return the (builtin) typenumber for the elements of this array.
-
 .. c:function:: PyObject *PyArray_GETITEM(PyArrayObject* arr, void* itemptr)
 
     Get a Python object of a builtin type from the ndarray, *arr*, 
     at the location pointed to by itemptr. Return ``NULL`` on failure.
     
     `numpy.ndarray.item` is identical to PyArray_GETITEM.
-    
-.. c:function:: int PyArray_SETITEM( \
-        PyArrayObject* arr, void* itemptr, PyObject* obj)
-
-    Convert obj and place it in the ndarray, *arr*, at the place
-    pointed to by itemptr. Return -1 if an error occurs or 0 on
-    success.
-
-.. c:function:: npy_intp PyArray_SIZE(PyArrayObject* arr)
-
-    Returns the total size (in number of elements) of the array.
-
-.. c:function:: npy_intp PyArray_Size(PyArrayObject* obj)
-
-    Returns 0 if *obj* is not a sub-class of ndarray. Otherwise,
-    returns the total number of elements in the array. Safer version
-    of :c:func:`PyArray_SIZE` (*obj*).
-
-.. c:function:: npy_intp PyArray_NBYTES(PyArrayObject* arr)
-
-    Returns the total number of bytes consumed by the array.
 
 
 Data access
@@ -1397,6 +1400,7 @@ Special functions for NPY_OBJECT
 
     Returns 0 for success, -1 for failure.
 
+.. _array-flags:
 
 Array flags
 -----------
diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst
index a716b5a06..336dff211 100644
--- a/doc/source/reference/c-api.types-and-structures.rst
+++ b/doc/source/reference/c-api.types-and-structures.rst
@@ -1,3 +1,4 @@
+
 *****************************
 Python Types and C-Structures
 *****************************
@@ -75,7 +76,8 @@ PyArray_Type and PyArrayObject
    these structure members should normally be accessed using the
    provided macros. If you need a shorter name, then you can make use
    of :c:type:`NPY_AO` (deprecated) which is defined to be equivalent to
-   :c:type:`PyArrayObject`.
+   :c:type:`PyArrayObject`. Direct access to the struct fields are
+   deprecated. Use the `PyArray_*(arr)` form instead.
 
    .. code-block:: c
 
@@ -103,7 +105,8 @@ PyArray_Type and PyArrayObject
 
 .. c:member:: char *PyArrayObject.data
 
-    A pointer to the first element of the array. This pointer can
+    Accessible via :c:data:`PyArray_DATA`, this data member is a
+    pointer to the first element of the array. This pointer can
     (and normally should) be recast to the data type of the array.
 
 .. c:member:: int PyArrayObject.nd
@@ -111,26 +114,29 @@ PyArray_Type and PyArrayObject
     An integer providing the number of dimensions for this
     array. When nd is 0, the array is sometimes called a rank-0
     array. Such arrays have undefined dimensions and strides and
-    cannot be accessed. :c:data:`NPY_MAXDIMS` is the largest number of
-    dimensions for any array.
+    cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in
+    ``ndarraytypes.h`` points to this data member. :c:data:`NPY_MAXDIMS`
+    is the largest number of dimensions for any array.
 
 .. c:member:: npy_intp PyArrayObject.dimensions
 
     An array of integers providing the shape in each dimension as
     long as nd :math:`\geq` 1. The integer is always large enough
     to hold a pointer on the platform, so the dimension size is
-    only limited by memory.
+    only limited by memory. :c:data:`PyArray_DIMS` is the macro
+    associated with this data member.
 
 .. c:member:: npy_intp *PyArrayObject.strides
 
     An array of integers providing for each dimension the number of
     bytes that must be skipped to get to the next element in that
-    dimension.
+    dimension. Associated with macro :c:data:`PyArray_STRIDES`.
 
 .. c:member:: PyObject *PyArrayObject.base
 
-    This member is used to hold a pointer to another Python object that
-    is related to this array. There are two use cases:
+    Pointed to by :c:data:`PyArray_BASE`, this member is used to hold a
+    pointer to another Python object that is related to this array.
+    There are two use cases:
 
     - If this array does not own its own memory, then base points to the
       Python object that owns it (perhaps another array object)
@@ -149,11 +155,13 @@ PyArray_Type and PyArrayObject
     descriptor structure for each data type supported. This
     descriptor structure contains useful information about the type
     as well as a pointer to a table of function pointers to
-    implement specific functionality.
+    implement specific functionality. As the name suggests, it is
+    associated with the macro :c:data:`PyArray_DESCR`.
 
 .. c:member:: int PyArrayObject.flags
 
-    Flags indicating how the memory pointed to by data is to be
+    Pointed to by the macro :c:data:`PyArray_FLAGS`, this data member represents
+    the flags indicating how the memory pointed to by data is to be
     interpreted. Possible flags are :c:data:`NPY_ARRAY_C_CONTIGUOUS`,
     :c:data:`NPY_ARRAY_F_CONTIGUOUS`, :c:data:`NPY_ARRAY_OWNDATA`,
     :c:data:`NPY_ARRAY_ALIGNED`, :c:data:`NPY_ARRAY_WRITEABLE`,