DOC: fixes from review

8 files changed, 92 insertions, 125 deletions

diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst
index 0b7482f2b..204ebfe08 100644
--- a/doc/source/reference/maskedarray.baseclass.rst
+++ b/doc/source/reference/maskedarray.baseclass.rst
@@ -49,11 +49,11 @@ The :class:`MaskedArray` class
 
 .. class:: MaskedArray
 
-   A subclass of :class:`~numpy.ndarray` designed to manipulate numerical arrays with missing data.
+A subclass of :class:`~numpy.ndarray` designed to manipulate numerical arrays with missing data.
 
 
 
- An instance of :class:`MaskedArray` can be thought as the combination of several elements:
+An instance of :class:`MaskedArray` can be thought as the combination of several elements:
 
 * The :attr:`~MaskedArray.data`, as a regular :class:`numpy.ndarray` of any shape or datatype (the data).
 * A boolean :attr:`~numpy.ma.MaskedArray.mask` with the same shape as the data, where a ``True`` value indicates that the corresponding element of the data is invalid.
@@ -69,91 +69,19 @@ Attributes and properties of masked arrays
 
 .. seealso:: :ref:`Array Attributes <arrays.ndarray.attributes>`
 
+.. autoattribute:: MaskedArray.data
 
-.. _ma-data:
-.. attribute:: MaskedArray.data
+.. autoattribute:: MaskedArray.mask
 
-   Returns the underlying data, as a view of the masked array.
-   If the underlying data is a subclass of :class:`numpy.ndarray`, it is
-   returned as such.
+.. autoattribute:: MaskedArray.recordmask
 
-      >>> x = ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
-      >>> x.data
-      matrix([[1, 2],
-              [3, 4]])
+.. autoattribute:: MaskedArray.fill_value
 
-   The type of the data can be accessed through the :attr:`baseclass`
-   attribute.
+.. autoattribute:: MaskedArray.baseclass
 
-.. _ma-mask:
-
-.. attribute:: MaskedArray.mask
-
-   Returns the underlying mask, as an array with the same shape and structure
-   as the data, but where all fields are atomically booleans.
-   A value of ``True`` indicates an invalid entry.
-
-
-.. _ma-recordmask:
-
-.. attribute:: MaskedArray.recordmask
-
-   Returns the mask of the array if it has no named fields. For structured
-   arrays, returns a ndarray of booleans where entries are ``True`` if **all**
-   the fields are masked, ``False`` otherwise::
-
-      >>> x = ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
-      ...         mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
-      ...        dtype=[('a', int), ('b', int)])
-      >>> x.recordmask
-      array([False, False,  True, False, False])
-
-
-.. _ma-fillvalue:
-
-.. attribute:: MaskedArray.fill_value
-
-   Returns the value used to fill the invalid entries of a masked array.
-   The value is either a scalar (if the masked array has no named fields),
-   or a 0-D ndarray with the same :attr:`dtype` as the masked array if it has
-   named fields.
-
-   The default filling value depends on the datatype of the array:
-
-   ========  ========
-   datatype  default
-   ========  ========
-   bool      True
-   int       999999
-   float     1.e20
-   complex   1.e20+0j
-   object    '?'
-   string    'N/A'
-   ========  ========
-
-
-
-.. attribute:: MaskedArray.baseclass
-
-   Returns the class of the underlying data.
-
-      >>> x =  ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 0], [1, 0]])
-      >>> x.baseclass
-      <class 'numpy.matrixlib.defmatrix.matrix'>
-
-
-.. attribute:: MaskedArray.sharedmask
-
-   Returns whether the mask of the array is shared between several masked arrays.
-   If this is the case, any modification to the mask of one array will be
-   propagated to the others.
-
-
-.. attribute:: MaskedArray.hardmask
-
-   Returns whether the mask is hard (``True``) or soft (``False``).
-   When the mask is hard, masked entries cannot be unmasked.
+.. autoattribute:: MaskedArray.sharedmask
 
+.. autoattribute:: MaskedArray.hardmask
 
 As :class:`MaskedArray` is a subclass of :class:`~numpy.ndarray`, a masked array also inherits all the attributes and properties of a  :class:`~numpy.ndarray` instance.
 
diff --git a/doc/source/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst
index b99378e42..491bb6bff 100644
--- a/doc/source/reference/routines.ma.rst
+++ b/doc/source/reference/routines.ma.rst
@@ -77,9 +77,11 @@ Inspecting the array
    ma.size
 
 
-.. seealso:: :ref:`ma.MaskedArray.data <ma-data>`,
-    :ref:`ma.MaskedArray.mask <ma-mask>` and
-    :ref:`ma.MaskedArray.recordmask <ma-recordmask>`
+.. autosummary::
+
+    ma.MaskedArray.data
+    ma.MaskedArray.mask
+    ma.MaskedArray.recordmask
 
 _____
 
@@ -287,7 +289,9 @@ Filling a masked array
    ma.MaskedArray.get_fill_value
    ma.MaskedArray.set_fill_value
 
-.. seealso: :ref:`ma.MaskedArray.fill_value <ma-fill_value>`
+.. autosummary::
+
+    ma.MaskedArray.fill_value
 
 _____
 
diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index e81d0f1ee..e2981b40e 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -16,7 +16,7 @@ A universal function (or :term:`ufunc` for short) is a function that
 operates on :class:`ndarrays <ndarray>` in an element-by-element fashion,
 supporting :ref:`array broadcasting <ufuncs.broadcasting>`, :ref:`type
 casting <ufuncs.casting>`, and several other standard features. That
-is, a ufunc is a ":term:`vectorized`" wrapper for a function that
+is, a ufunc is a ":term:`vectorized <vectorization>`" wrapper for a function that
 takes a fixed number of specific inputs and produces a fixed number of
 specific outputs.
 
diff --git a/doc/source/user/whatisnumpy.rst b/doc/source/user/whatisnumpy.rst
index d47c105ba..dfd79671a 100644
--- a/doc/source/user/whatisnumpy.rst
+++ b/doc/source/user/whatisnumpy.rst
@@ -91,6 +91,11 @@ idiom is even simpler!  This last example illustrates two of NumPy's
 features which are the basis of much of its power: vectorization and
 broadcasting.
 
+.. _whatis-vectorization:
+
+Why is NumPy Fast?
+------------------
+
 Vectorization describes the absence of any explicit looping, indexing,
 etc., in the code - these things are taking place, of course, just
 "behind the scenes" in optimized, pre-compiled C code.  Vectorized
@@ -120,8 +125,13 @@ the shape of the larger in such a way that the resulting broadcast is
 unambiguous. For detailed "rules" of broadcasting see
 `numpy.doc.broadcasting`.
 
+Who Else Uses NumPy?
+--------------------
+
 NumPy fully supports an object-oriented approach, starting, once
 again, with `ndarray`.  For example, `ndarray` is a class, possessing
 numerous methods and attributes.  Many of its methods are mirrored by
 functions in the outer-most NumPy namespace, allowing the programmer
-to code in whichever paradigm they prefer.
+to code in whichever paradigm they prefer. This flexibility has allowed the
+NumPy array dialect and NumPy `ndarray` class to become the *de-facto* language
+of mulit-dimensional data interchange used in Python.
diff --git a/numpy/doc/glossary.py b/numpy/doc/glossary.py
index 162288b14..292f293b7 100644
--- a/numpy/doc/glossary.py
+++ b/numpy/doc/glossary.py
@@ -348,31 +348,31 @@ Glossary
          Painting the city red!
 
    slice
-       Used to select only certain elements from a sequence::
+       Used to select only certain elements from a sequence:
 
-         >>> x = range(5)
-         >>> x
-         [0, 1, 2, 3, 4]
+       >>> x = range(5)
+       >>> x
+       [0, 1, 2, 3, 4]
 
-         >>> x[1:3] # slice from 1 to 3 (excluding 3 itself)
-         [1, 2]
+       >>> x[1:3] # slice from 1 to 3 (excluding 3 itself)
+       [1, 2]
 
-         >>> x[1:5:2] # slice from 1 to 5, but skipping every second element
-         [1, 3]
+       >>> x[1:5:2] # slice from 1 to 5, but skipping every second element
+       [1, 3]
 
-         >>> x[::-1] # slice a sequence in reverse
-         [4, 3, 2, 1, 0]
+       >>> x[::-1] # slice a sequence in reverse
+       [4, 3, 2, 1, 0]
 
        Arrays may have more than one dimension, each which can be sliced
-       individually::
+       individually:
 
-         >>> x = np.array([[1, 2], [3, 4]])
-         >>> x
-         array([[1, 2],
-                [3, 4]])
+       >>> x = np.array([[1, 2], [3, 4]])
+       >>> x
+       array([[1, 2],
+              [3, 4]])
 
-         >>> x[:, 1]
-         array([2, 4])
+       >>> x[:, 1]
+       array([2, 4])
 
    structure
        See :term:`structured data type`
@@ -380,9 +380,14 @@ Glossary
    structured data type
        A data type composed of other datatypes
 
-   subarray
+   subarray data type
        A :term:`structured data type` may contain a :term:`ndarray` with its
-       own dtype and shape.
+       own dtype and shape:
+
+       >>> dt = np.dtype([('a', np.int32), ('b', np.float32, (3,))])
+       >>> np.zeros(3, dtype=dt)
+       array([(0, [0., 0., 0.]), (0, [0., 0., 0.]), (0, [0., 0., 0.])],
+             dtype=[('a', '<i4'), ('b', '<f4', (3,))])
 
    title
        In addition to field names, structured array fields may have an
@@ -425,14 +430,17 @@ Glossary
          'alpha'
 
    ufunc
-       Universal function.  A fast element-wise array operation.  Examples include
-       ``add``, ``sin`` and ``logical_or``.
-
-   vectorized
-       A loop-based function that operates on data with fixed strides.
-       Compilers know how to take advantage of well-constructed loops and
-       match the data to specialized hardware that can operate on a number
-       of operands in parallel.
+       Universal function.  A fast element-wise, :term:`vectorized
+       <vectorization>` array operation.  Examples include ``add``, ``sin`` and
+       ``logical_or``.
+
+   vectorization
+       Optimizing a looping block by specialized code. In a traditional send,
+       vectorization operates on data with fixed strides via specialized
+       hardware. Compilers know how to take advantage of well-constructed loops
+       and match the data to specialized hardware that can operate on a number
+       of operands in parallel. NumPy uses :ref:`vectorization
+       <whatis-vectorization>` to mean any optimization via specialized code. 
 
    view
        An array that does not own its data, but refers to another array's
diff --git a/numpy/doc/structured_arrays.py b/numpy/doc/structured_arrays.py
index c3605b49a..c0437dc07 100644
--- a/numpy/doc/structured_arrays.py
+++ b/numpy/doc/structured_arrays.py
@@ -57,10 +57,10 @@ A structured datatype can be thought of as a sequence of bytes of a certain
 length (the structure's :term:`itemsize`) which is interpreted as a collection
 of fields. Each field has a name, a datatype, and a byte offset within the
 structure. The datatype of a field may be any numpy datatype including other
-structured datatypes, and it may also be a :term:`subarray` which behaves like
-an ndarray of a specified shape. The offsets of the fields are arbitrary, and
-fields may even overlap. These offsets are usually determined automatically by
-numpy, but can also be specified.
+structured datatypes, and it may also be a :term:`subarray data type` which
+behaves like an ndarray of a specified shape. The offsets of the fields are
+arbitrary, and fields may even overlap. These offsets are usually determined
+automatically by numpy, but can also be specified.
 
 Structured Datatype Creation
 ----------------------------
@@ -266,7 +266,7 @@ providing a 3-element tuple ``(datatype, offset, title)`` instead of the usual
  >>> np.dtype({'name': ('i4', 0, 'my title')})
  dtype([(('my title', 'name'), '<i4')])
 
-The ``dtype.fields`` dictionary will contain title as keys, if any
+The ``dtype.fields`` dictionary will contain titles as keys, if any
 titles are used.  This means effectively that a field with a title will be
 represented twice in the fields dictionary. The tuple values for these fields
 will also have a third element, the field title. Because of this, and because
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
index 16dc10293..b8fd76860 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -3448,6 +3448,7 @@ class MaskedArray(ndarray):
     @property
     def mask(self):
         """ Current mask. """
+
         # We could try to force a reshape, but that wouldn't work in some
         # cases.
         return self._mask
@@ -3459,11 +3460,17 @@ class MaskedArray(ndarray):
     @property
     def recordmask(self):
         """
-        Return the mask of the records.
-
-        A record is masked when all the fields are masked.
+        Get or set the mask of the array if it has no named fields. For
+        structured arrays, returns a ndarray of booleans where entries are
+        ``True`` if **all** the fields are masked, ``False`` otherwise:
 
+        >>> x = np.ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
+        ...         mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
+        ...        dtype=[('a', int), ('b', int)])
+        >>> x.recordmask
+        array([False, False,  True, False, False])
         """
+
         _mask = self._mask.view(ndarray)
         if _mask.dtype.names is None:
             return _mask
@@ -3568,9 +3575,19 @@ class MaskedArray(ndarray):
         return self._baseclass
 
     def _get_data(self):
-        """Return the current data, as a view of the original
-        underlying data.
+        """
+        Returns the underlying data, as a view of the masked array.
 
+        If the underlying data is a subclass of :class:`numpy.ndarray`, it is
+        returned as such.
+
+        >>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
+        >>> x.data
+        matrix([[1, 2],
+                [3, 4]])
+
+        The type of the data can be accessed through the :attr:`baseclass`
+        attribute.
         """
         return ndarray.view(self, self._baseclass)
 
diff --git a/tools/refguide_check.py b/tools/refguide_check.py
index 531eeacb0..74dbad78b 100644
--- a/tools/refguide_check.py
+++ b/tools/refguide_check.py
@@ -311,7 +311,7 @@ def validate_rst_syntax(text, name, dots=True):
         return False, "ERROR: %s: no documentation" % (name,)
 
     ok_unknown_items = set([
-        'mod', 'currentmodule', 'autosummary', 'data',
+        'mod', 'currentmodule', 'autosummary', 'data', 'attr',
         'obj', 'versionadded', 'versionchanged', 'module', 'class',
         'ref', 'func', 'toctree', 'moduleauthor', 'term', 'c:member',
         'sectionauthor', 'codeauthor', 'eq', 'doi', 'DOI', 'arXiv', 'arxiv'