DOC: Remove duplicate documentation of the PyArray_SimpleNew family of functions

2 files changed, 19 insertions, 41 deletions

diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 7d6942f75..aeb55ca03 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -291,9 +291,14 @@ From scratch
 .. c:function:: PyObject* PyArray_SimpleNew(int nd, npy_intp* dims, int typenum)
 
     Create a new uninitialized array of type, *typenum*, whose size in
-    each of *nd* dimensions is given by the integer array, *dims*.
-    This function cannot be used to create a flexible-type array (no
-    itemsize given).
+    each of *nd* dimensions is given by the integer array, *dims*.The memory
+    for the array is uninitialized (unless typenum is :c:data:`NPY_OBJECT`
+    in which case each element in the array is set to NULL). The
+    *typenum* argument allows specification of any of the builtin
+    data-types such as :c:data:`NPY_FLOAT` or :c:data:`NPY_LONG`. The
+    memory for the array can be set to zero if desired using
+    :c:func:`PyArray_FILLWBYTE` (return_object, 0).This function cannot be
+    used to create a flexible-type array (no itemsize given).
 
 .. c:function:: PyObject* PyArray_SimpleNewFromData( \
         int nd, npy_intp* dims, int typenum, void* data)
@@ -302,7 +307,13 @@ From scratch
     pointer. The array flags will have a default that the data area is
     well-behaved and C-style contiguous. The shape of the array is
     given by the *dims* c-array of length *nd*. The data-type of the
-    array is indicated by *typenum*.
+    array is indicated by *typenum*. If data comes from another
+    reference-counted Python object, the reference count on this object
+    should be increased after the pointer is passed in, and the base member
+    of the returned ndarray should point to the Python object that owns
+    the data. This will ensure that the provided memory is not
+    freed while the returned array is in existence. To free memory as soon
+    as the ndarray is deallocated, set the OWNDATA flag on the returned ndarray.
 
 .. c:function:: PyObject* PyArray_SimpleNewFromDescr( \
         int nd, npy_intp* dims, PyArray_Descr* descr)
diff --git a/doc/source/user/c-info.how-to-extend.rst b/doc/source/user/c-info.how-to-extend.rst
index b70036c89..3961325fb 100644
--- a/doc/source/user/c-info.how-to-extend.rst
+++ b/doc/source/user/c-info.how-to-extend.rst
@@ -504,7 +504,7 @@ writeable). The syntax is
 Creating a brand-new ndarray
 ----------------------------
 
-Quite often new arrays must be created from within extension-module
+Quite often, new arrays must be created from within extension-module
 code. Perhaps an output array is needed and you don't want the caller
 to have to supply it. Perhaps only a temporary array is needed to hold
 an intermediate calculation. Whatever the need there are simple ways
@@ -512,42 +512,9 @@ to get an ndarray object of whatever data-type is needed. The most
 general function for doing this is :c:func:`PyArray_NewFromDescr`. All array
 creation functions go through this heavily re-used code. Because of
 its flexibility, it can be somewhat confusing to use. As a result,
-simpler forms exist that are easier to use.
-
-:c:func:`PyArray_SimpleNew`
-
-    This function allocates new memory and places it in an ndarray
-    with *nd* dimensions whose shape is determined by the array of
-    at least *nd* items pointed to by *dims*. The memory for the
-    array is uninitialized (unless typenum is :c:data:`NPY_OBJECT` in
-    which case each element in the array is set to NULL). The
-    *typenum* argument allows specification of any of the builtin
-    data-types such as :c:data:`NPY_FLOAT` or :c:data:`NPY_LONG`. The
-    memory for the array can be set to zero if desired using
-    :c:func:`PyArray_FILLWBYTE` (return_object, 0).
-
-:c:func:`PyArray_SimpleNewFromData`
-
-    Sometimes, you want to wrap memory allocated elsewhere into an
-    ndarray object for downstream use. This routine makes it
-    straightforward to do that. The first three arguments are the same
-    as in :c:func:`PyArray_SimpleNew`, the final argument is a pointer to a
-    block of contiguous memory that the ndarray should use as it's
-    data-buffer which will be interpreted in C-style contiguous
-    fashion. A new reference to an ndarray is returned, but the
-    ndarray will not own its data. When this ndarray is deallocated,
-    the pointer will not be freed.
-
-    You should ensure that the provided memory is not freed while the
-    returned array is in existence. The easiest way to handle this is
-    if data comes from another reference-counted Python object. The
-    reference count on this object should be increased after the
-    pointer is passed in, and the base member of the returned ndarray
-    should point to the Python object that owns the data. Then, when
-    the ndarray is deallocated, the base-member will be DECREF'd
-    appropriately. If you want the memory to be freed as soon as the
-    ndarray is deallocated then simply set the OWNDATA flag on the
-    returned ndarray.
+simpler forms exist that are easier to use. These forms are part of the
+:c:func:`PyArray_SimpleNew` family of functions, which simplify the interface
+by providing default values for common use cases.
 
 
 Getting at ndarray memory and accessing elements of the ndarray