DOC: improve record/structured array nomenclature & guide

This update adds a section better describing record arrays in the user
guide (numpy/doc/structured_arrays.py).

It also corrects nomenclature, such that "structured array" refers to
ndarrays with structured dtype, "record array" refers to modified
ndarrays as created by np.rec.array, and "recarray" refers to ndarrays
viewed as np.recarray. See the note at the end of the structured
array user guide.

9 files changed, 53 insertions, 52 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index e77dfc31e..caaf3a73b 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -337,7 +337,7 @@ Record arrays (:mod:`numpy.rec`)
              :ref:`arrays.dtypes`.
 
 Numpy provides the :class:`recarray` class which allows accessing the
-fields of a record/structured array as attributes, and a corresponding
+fields of a structured array as attributes, and a corresponding
 scalar data type object :class:`record`.
 
 .. currentmodule:: numpy
diff --git a/doc/source/reference/arrays.dtypes.rst b/doc/source/reference/arrays.dtypes.rst
index 797f1f6f8..a43c23218 100644
--- a/doc/source/reference/arrays.dtypes.rst
+++ b/doc/source/reference/arrays.dtypes.rst
@@ -14,12 +14,12 @@ following aspects of the data:
 1. Type of the data (integer, float, Python object, etc.)
 2. Size of the data (how many bytes is in *e.g.* the integer)
 3. Byte order of the data (:term:`little-endian` or :term:`big-endian`)
-4. If the data type is a :term:`record`, an aggregate of other
+4. If the data type is :term:`structured`, an aggregate of other
    data types, (*e.g.*, describing an array item consisting of
    an integer and a float),
 
-   1. what are the names of the ":term:`fields <field>`" of the record,
-      by which they can be :ref:`accessed <arrays.indexing.rec>`,
+   1. what are the names of the ":term:`fields <field>`" of the structure,
+      by which they can be :ref:`accessed <arrays.indexing.fields>`,
    2. what is the data-type of each :term:`field`, and
    3. which part of the memory block each field takes.
 
@@ -40,15 +40,14 @@ needed in Numpy.
 
 .. index::
    pair: dtype; field
-   pair: dtype; record
 
-Struct data types are formed by creating a data type whose
+Structured data types are formed by creating a data type whose
 :term:`fields` contain other data types. Each field has a name by
-which it can be :ref:`accessed <arrays.indexing.rec>`. The parent data
+which it can be :ref:`accessed <arrays.indexing.fields>`. The parent data
 type should be of sufficient size to contain all its fields; the
 parent is nearly always based on the :class:`void` type which allows
-an arbitrary item size. Struct data types may also contain nested struct
-sub-array data types in their fields.
+an arbitrary item size. Structured data types may also contain nested 
+structured sub-array data types in their fields.
 
 .. index::
    pair: dtype; sub-array
@@ -60,7 +59,7 @@ fixed size.
 If an array is created using a data-type describing a sub-array,
 the dimensions of the sub-array are appended to the shape
 of the array when the array is created. Sub-arrays in a field of a
-record behave differently, see :ref:`arrays.indexing.rec`.
+structured type behave differently, see :ref:`arrays.indexing.fields`.
 
 Sub-arrays always have a C-contiguous memory layout.
 
@@ -83,7 +82,7 @@ Sub-arrays always have a C-contiguous memory layout.
 
 .. admonition:: Example
 
-   A record data type containing a 16-character string (in field 'name')
+   A structured data type containing a 16-character string (in field 'name')
    and a sub-array of two 64-bit floating-point number (in field 'grades'):
 
    >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
@@ -246,8 +245,8 @@ Array-protocol type strings (see :ref:`arrays.interface`)
 
 String with comma-separated fields
 
-   Numarray introduced a short-hand notation for specifying the format
-   of a record as a comma-separated string of basic formats.
+   A short-hand notation for specifying the format of a structured data type is
+   a comma-separated string of basic formats.
 
    A basic format in this context is an optional shape specifier
    followed by an array-protocol type string. Parenthesis are required
@@ -315,7 +314,7 @@ Type strings
 
        >>> dt = np.dtype((np.int32, (2,2)))          # 2 x 2 integer sub-array
        >>> dt = np.dtype(('S10', 1))                 # 10-character string
-       >>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 record sub-array
+       >>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 structured sub-array
 
 .. index::
    triple: dtype; construction; from list
@@ -432,7 +431,8 @@ Type strings
     Both arguments must be convertible to data-type objects in this
     case. The *base_dtype* is the data-type object that the new
     data-type builds on. This is how you could assign named fields to
-    any built-in data-type object.
+    any built-in data-type object, as done in 
+    :ref:`record arrays <arrays.classes.rec>`.
 
     .. admonition:: Example
 
@@ -486,7 +486,7 @@ Endianness of this data:
 
    dtype.byteorder
 
-Information about sub-data-types in a :term:`record`:
+Information about sub-data-types in a :term:`structured` data type:
 
 .. autosummary::
    :toctree: generated/
diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst
index ef0180e0f..2eb07c4e0 100644
--- a/doc/source/reference/arrays.indexing.rst
+++ b/doc/source/reference/arrays.indexing.rst
@@ -11,7 +11,7 @@ Indexing
 
 :class:`ndarrays <ndarray>` can be indexed using the standard Python
 ``x[obj]`` syntax, where *x* is the array and *obj* the selection.
-There are three kinds of indexing available: record access, basic
+There are three kinds of indexing available: field access, basic
 slicing, advanced indexing. Which one occurs depends on *obj*.
 
 .. note::
@@ -489,25 +489,25 @@ indexing (in no particular order):
   view on the data. This *must* be done if the subclasses ``__getitem__`` does
   not return views.
 
-.. _arrays.indexing.rec:
+.. _arrays.indexing.fields:
 
 
-Record Access
+Field Access
 -------------
 
 .. seealso:: :ref:`arrays.dtypes`, :ref:`arrays.scalars`
 
-If the :class:`ndarray` object is a record array, *i.e.* its data type
-is a :term:`record` data type, the :term:`fields <field>` of the array
-can be accessed by indexing the array with strings, dictionary-like.
+If the :class:`ndarray` object is a structured array the :term:`fields <field>`
+of the array can be accessed by indexing the array with strings,
+dictionary-like.
 
 Indexing ``x['field-name']`` returns a new :term:`view` to the array,
 which is of the same shape as *x* (except when the field is a
 sub-array) but of data type ``x.dtype['field-name']`` and contains
-only the part of the data in the specified field. Also record array
-scalars can be "indexed" this way.
+only the part of the data in the specified field. Also 
+:ref:`record array <arrays.classes.rec>` scalars can be "indexed" this way.
 
-Indexing into a record array can also be done with a list of field names,
+Indexing into a structured array can also be done with a list of field names,
 *e.g.* ``x[['field-name1','field-name2']]``. Currently this returns a new
 array containing a copy of the values in the fields specified in the list.
 As of NumPy 1.7, returning a copy is being deprecated in favor of returning
diff --git a/doc/source/reference/arrays.interface.rst b/doc/source/reference/arrays.interface.rst
index 16abe5ce1..50595c2d8 100644
--- a/doc/source/reference/arrays.interface.rst
+++ b/doc/source/reference/arrays.interface.rst
@@ -103,19 +103,19 @@ This approach to the interface consists of the object having an
        not a requirement.  The only requirement is that the number of
        bytes represented in the *typestr* key is the same as the total
        number of bytes represented here.  The idea is to support
-       descriptions of C-like structs (records) that make up array
+       descriptions of C-like structs that make up array
        elements.  The elements of each tuple in the list are
 
        1.  A string providing a name associated with this portion of
-           the record.  This could also be a tuple of ``('full name',
+           the datatype.  This could also be a tuple of ``('full name',
 	   'basic_name')`` where basic name would be a valid Python
            variable name representing the full name of the field.
 
        2. Either a basic-type description string as in *typestr* or
-          another list (for nested records)
+          another list (for nested structured types)
 
        3. An optional shape tuple providing how many times this part
-          of the record should be repeated.  No repeats are assumed
+          of the structure should be repeated.  No repeats are assumed
           if this is not given.  Very complicated structures can be
           described using this generic interface.  Notice, however,
           that each element of the array is still of the same
@@ -301,7 +301,8 @@ more information which may be important for various applications::
          typestr == '|V16'
          descr == [('ival','>i4'),('','|V4'),('dval','>f8')]
 
-It should be clear that any record type could be described using this interface.
+It should be clear that any structured type could be described using this
+interface.
 
 Differences with Array interface (Version 2)
 ============================================
diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst
index e9c0a6d87..c8d834d1c 100644
--- a/doc/source/reference/arrays.ndarray.rst
+++ b/doc/source/reference/arrays.ndarray.rst
@@ -82,7 +82,7 @@ Indexing arrays
 
 Arrays can be indexed using an extended Python slicing syntax,
 ``array[selection]``.  Similar syntax is also used for accessing
-fields in a :ref:`record array <arrays.dtypes>`.
+fields in a :ref:`structured array <arrays.dtypes.field>`.
 
 .. seealso:: :ref:`Array Indexing <arrays.indexing>`.
 
diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst
index f229efb07..652fa62e1 100644
--- a/doc/source/reference/arrays.scalars.rst
+++ b/doc/source/reference/arrays.scalars.rst
@@ -250,7 +250,7 @@ array scalar,
 
 - ``x[()]`` returns a 0-dimensional :class:`ndarray`
 - ``x['field-name']`` returns the array scalar in the field *field-name*.
-  (*x* can have fields, for example, when it corresponds to a record data type.)
+  (*x* can have fields, for example, when it corresponds to a structured data type.)
 
 Methods
 =======
@@ -282,10 +282,10 @@ Defining new types
 ==================
 
 There are two ways to effectively define a new array scalar type
-(apart from composing record :ref:`dtypes <arrays.dtypes>` from the built-in
-scalar types): One way is to simply subclass the :class:`ndarray` and
-overwrite the methods of interest. This will work to a degree, but
-internally certain behaviors are fixed by the data type of the array.
-To fully customize the data type of an array you need to define a new
-data-type, and register it with NumPy. Such new types can only be
-defined in C, using the :ref:`Numpy C-API <c-api>`.
+(apart from composing structured types :ref:`dtypes <arrays.dtypes>` from 
+the built-in scalar types): One way is to simply subclass the 
+:class:`ndarray` and overwrite the methods of interest. This will work to 
+a degree, but internally certain behaviors are fixed by the data type of 
+the array.  To fully customize the data type of an array you need to 
+define a new data-type, and register it with NumPy. Such new types can only 
+be defined in C, using the :ref:`Numpy C-API <c-api>`.
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 08eba243e..9b8cc04b6 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -1240,9 +1240,9 @@ Special functions for NPY_OBJECT
 
     A function to INCREF all the objects at the location *ptr*
     according to the data-type *dtype*. If *ptr* is the start of a
-    record with an object at any offset, then this will (recursively)
+    structured type with an object at any offset, then this will (recursively)
     increment the reference count of all object-like items in the
-    record.
+    structured type.
 
 .. cfunction:: int PyArray_XDECREF(PyArrayObject* op)
 
@@ -1253,7 +1253,7 @@ Special functions for NPY_OBJECT
 
 .. cfunction:: void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)
 
-    A function to XDECREF all the object-like items at the loacation
+    A function to XDECREF all the object-like items at the location
     *ptr* as recorded in the data-type, *dtype*. This works
     recursively so that if ``dtype`` itself has fields with data-types
     that contain object-like items, all the object-like fields will be
@@ -1540,7 +1540,7 @@ Conversion
     itemsize of the new array type must be less than *self*
     ->descr->elsize or an error is raised. The same shape and strides
     as the original array are used. Therefore, this function has the
-    effect of returning a field from a record array. But, it can also
+    effect of returning a field from a structured array. But, it can also
     be used to select specific bytes or groups of bytes from any array
     type.
 
@@ -1786,7 +1786,7 @@ Item selection and manipulation
     ->descr is a data-type with fields defined, then
     self->descr->names is used to determine the sort order. A
     comparison where the first field is equal will use the second
-    field and so on. To alter the sort order of a record array, create
+    field and so on. To alter the sort order of a structured array, create
     a new data-type with a different order of names and construct a
     view of the array with that new data-type.
 
@@ -1805,7 +1805,7 @@ Item selection and manipulation
     to understand the order the *sort_keys* must be in (reversed from
     the order you would use when comparing two elements).
 
-    If these arrays are all collected in a record array, then
+    If these arrays are all collected in a structured array, then
     :cfunc:`PyArray_Sort` (...) can also be used to sort the array
     directly.
 
@@ -1838,7 +1838,7 @@ Item selection and manipulation
     If *self*->descr is a data-type with fields defined, then
     self->descr->names is used to determine the sort order. A comparison where
     the first field is equal will use the second field and so on. To alter the
-    sort order of a record array, create a new data-type with a different
+    sort order of a structured array, create a new data-type with a different
     order of names and construct a view of the array with that new data-type.
     Returns zero on success and -1 on failure.
 
diff --git a/doc/source/reference/internals.code-explanations.rst b/doc/source/reference/internals.code-explanations.rst
index 580661cb3..f01300e25 100644
--- a/doc/source/reference/internals.code-explanations.rst
+++ b/doc/source/reference/internals.code-explanations.rst
@@ -74,9 +74,9 @@ optimizations that by-pass this mechanism, but the point of the data-
 type abstraction is to allow new data-types to be added.
 
 One of the built-in data-types, the void data-type allows for
-arbitrary records containing 1 or more fields as elements of the
+arbitrary structured types containing 1 or more fields as elements of the
 array. A field is simply another data-type object along with an offset
-into the current record. In order to support arbitrarily nested
+into the current structured type. In order to support arbitrarily nested
 fields, several recursive implementations of data-type access are
 implemented for the void type. A common idiom is to cycle through the
 elements of the dictionary and perform a specific operation based on
@@ -184,7 +184,7 @@ The array scalars also offer the same methods and attributes as arrays
 with the intent that the same code can be used to support arbitrary
 dimensions (including 0-dimensions). The array scalars are read-only
 (immutable) with the exception of the void scalar which can also be
-written to so that record-array field setting works more naturally
+written to so that structured array field setting works more naturally
 (a[0]['f1'] = ``value`` ).
 
 
diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst
index ce6c3b851..1be5af081 100644
--- a/doc/source/user/basics.rec.rst
+++ b/doc/source/user/basics.rec.rst
@@ -1,7 +1,7 @@
 .. _structured_arrays:
 
-***************************************
-Structured arrays (aka "Record arrays")
-***************************************
+*****************
+Structured arrays 
+*****************
 
 .. automodule:: numpy.doc.structured_arrays