Merge pull request #13002 from mattip/doc-warnings2

DOC: reduce warnings when building, and rephrase slightly

8 files changed, 161 insertions, 107 deletions

diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
index 2f5a48ed8..d6c784ba1 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -161,62 +161,63 @@ add_newdoc('numpy.core', 'nditer',
     ----------
     op : ndarray or sequence of array_like
         The array(s) to iterate over.
+
     flags : sequence of str, optional
-        Flags to control the behavior of the iterator.
+          Flags to control the behavior of the iterator.
 
-          * "buffered" enables buffering when required.
-          * "c_index" causes a C-order index to be tracked.
-          * "f_index" causes a Fortran-order index to be tracked.
-          * "multi_index" causes a multi-index, or a tuple of indices
+          * ``buffered`` enables buffering when required.
+          * ``c_index`` causes a C-order index to be tracked.
+          * ``f_index`` causes a Fortran-order index to be tracked.
+          * ``multi_index`` causes a multi-index, or a tuple of indices
             with one per iteration dimension, to be tracked.
-          * "common_dtype" causes all the operands to be converted to
+          * ``common_dtype`` causes all the operands to be converted to
             a common data type, with copying or buffering as necessary.
-          * "copy_if_overlap" causes the iterator to determine if read
+          * ``copy_if_overlap`` causes the iterator to determine if read
             operands have overlap with write operands, and make temporary
             copies as necessary to avoid overlap. False positives (needless
             copying) are possible in some cases.
-          * "delay_bufalloc" delays allocation of the buffers until
-            a reset() call is made. Allows "allocate" operands to
+          * ``delay_bufalloc`` delays allocation of the buffers until
+            a reset() call is made. Allows ``allocate`` operands to
             be initialized before their values are copied into the buffers.
-          * "external_loop" causes the `values` given to be
+          * ``external_loop`` causes the ``values`` given to be
             one-dimensional arrays with multiple values instead of
             zero-dimensional arrays.
-          * "grow_inner" allows the `value` array sizes to be made
-            larger than the buffer size when both "buffered" and
-            "external_loop" is used.
-          * "ranged" allows the iterator to be restricted to a sub-range
+          * ``grow_inner`` allows the ``value`` array sizes to be made
+            larger than the buffer size when both ``buffered`` and
+            ``external_loop`` is used.
+          * ``ranged`` allows the iterator to be restricted to a sub-range
             of the iterindex values.
-          * "refs_ok" enables iteration of reference types, such as
+          * ``refs_ok`` enables iteration of reference types, such as
             object arrays.
-          * "reduce_ok" enables iteration of "readwrite" operands
+          * ``reduce_ok`` enables iteration of ``readwrite`` operands
             which are broadcasted, also known as reduction operands.
-          * "zerosize_ok" allows `itersize` to be zero.
+          * ``zerosize_ok`` allows `itersize` to be zero.
     op_flags : list of list of str, optional
-        This is a list of flags for each operand. At minimum, one of
-        "readonly", "readwrite", or "writeonly" must be specified.
-
-          * "readonly" indicates the operand will only be read from.
-          * "readwrite" indicates the operand will be read from and written to.
-          * "writeonly" indicates the operand will only be written to.
-          * "no_broadcast" prevents the operand from being broadcasted.
-          * "contig" forces the operand data to be contiguous.
-          * "aligned" forces the operand data to be aligned.
-          * "nbo" forces the operand data to be in native byte order.
-          * "copy" allows a temporary read-only copy if required.
-          * "updateifcopy" allows a temporary read-write copy if required.
-          * "allocate" causes the array to be allocated if it is None
-            in the `op` parameter.
-          * "no_subtype" prevents an "allocate" operand from using a subtype.
-          * "arraymask" indicates that this operand is the mask to use
+          This is a list of flags for each operand. At minimum, one of
+          ``readonly``, ``readwrite``, or ``writeonly`` must be specified.
+
+          * ``readonly`` indicates the operand will only be read from.
+          * ``readwrite`` indicates the operand will be read from and written to.
+          * ``writeonly`` indicates the operand will only be written to.
+          * ``no_broadcast`` prevents the operand from being broadcasted.
+          * ``contig`` forces the operand data to be contiguous.
+          * ``aligned`` forces the operand data to be aligned.
+          * ``nbo`` forces the operand data to be in native byte order.
+          * ``copy`` allows a temporary read-only copy if required.
+          * ``updateifcopy`` allows a temporary read-write copy if required.
+          * ``allocate`` causes the array to be allocated if it is None
+            in the ``op`` parameter.
+          * ``no_subtype`` prevents an ``allocate`` operand from using a subtype.
+          * ``arraymask`` indicates that this operand is the mask to use
             for selecting elements when writing to operands with the
             'writemasked' flag set. The iterator does not enforce this,
             but when writing from a buffer back to the array, it only
             copies those elements indicated by this mask.
-          * 'writemasked' indicates that only elements where the chosen
-            'arraymask' operand is True will be written to.
-          * "overlap_assume_elementwise" can be used to mark operands that are
+          * ``writemasked`` indicates that only elements where the chosen
+            ``arraymask`` operand is True will be written to.
+          * ``overlap_assume_elementwise`` can be used to mark operands that are
             accessed only in the iterator order, to allow less conservative
-            copying when "copy_if_overlap" is present.
+            copying when ``copy_if_overlap`` is present.
     op_dtypes : dtype or tuple of dtype(s), optional
         The required data type(s) of the operands. If copying or buffering
         is enabled, the data will be converted to/from their original types.
@@ -225,7 +226,7 @@ add_newdoc('numpy.core', 'nditer',
         Fortran order, 'A' means 'F' order if all the arrays are Fortran
         contiguous, 'C' order otherwise, and 'K' means as close to the
         order the array elements appear in memory as possible. This also
-        affects the element memory order of "allocate" operands, as they
+        affects the element memory order of ``allocate`` operands, as they
         are allocated to be compatible with iteration order.
         Default is 'K'.
     casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
@@ -233,20 +234,20 @@ add_newdoc('numpy.core', 'nditer',
         or buffering.  Setting this to 'unsafe' is not recommended,
         as it can adversely affect accumulations.
 
-          * 'no' means the data types should not be cast at all.
-          * 'equiv' means only byte-order changes are allowed.
-          * 'safe' means only casts which can preserve values are allowed.
-          * 'same_kind' means only safe casts or casts within a kind,
-            like float64 to float32, are allowed.
-          * 'unsafe' means any data conversions may be done.
+        * 'no' means the data types should not be cast at all.
+        * 'equiv' means only byte-order changes are allowed.
+        * 'safe' means only casts which can preserve values are allowed.
+        * 'same_kind' means only safe casts or casts within a kind,
+          like float64 to float32, are allowed.
+        * 'unsafe' means any data conversions may be done.
     op_axes : list of list of ints, optional
         If provided, is a list of ints or None for each operands.
         The list of axes for an operand is a mapping from the dimensions
         of the iterator to the dimensions of the operand. A value of
         -1 can be placed for entries, causing that dimension to be
-        treated as "newaxis".
+        treated as `newaxis`.
     itershape : tuple of ints, optional
-        The desired shape of the iterator. This allows "allocate" operands
+        The desired shape of the iterator. This allows ``allocate`` operands
         with a dimension mapped by op_axes not corresponding to a dimension
         of a different operand to get a value not equal to 1 for that
         dimension.
@@ -263,19 +264,19 @@ add_newdoc('numpy.core', 'nditer',
     finished : bool
         Whether the iteration over the operands is finished or not.
     has_delayed_bufalloc : bool
-        If True, the iterator was created with the "delay_bufalloc" flag,
+        If True, the iterator was created with the ``delay_bufalloc`` flag,
         and no reset() function was called on it yet.
     has_index : bool
-        If True, the iterator was created with either the "c_index" or
-        the "f_index" flag, and the property `index` can be used to
+        If True, the iterator was created with either the ``c_index`` or
+        the ``f_index`` flag, and the property `index` can be used to
         retrieve it.
     has_multi_index : bool
-        If True, the iterator was created with the "multi_index" flag,
+        If True, the iterator was created with the ``multi_index`` flag,
         and the property `multi_index` can be used to retrieve it.
     index
-        When the "c_index" or "f_index" flag was used, this property
+        When the ``c_index`` or ``f_index`` flag was used, this property
         provides access to the index. Raises a ValueError if accessed
-        and `has_index` is False.
+        and ``has_index`` is False.
     iterationneedsapi : bool
         Whether iteration requires access to the Python API, for example
         if one of the operands is an object array.
@@ -288,11 +289,11 @@ add_newdoc('numpy.core', 'nditer',
         and optimized iterator access pattern. Valid only before the iterator
         is closed.
     multi_index
-        When the "multi_index" flag was used, this property
+        When the ``multi_index`` flag was used, this property
         provides access to the index. Raises a ValueError if accessed
-        accessed and `has_multi_index` is False.
+        accessed and ``has_multi_index`` is False.
     ndim : int
-        The iterator's dimension.
+        The dimensions of the iterator.
     nop : int
         The number of iterator operands.
     operands : tuple of operand(s)
@@ -301,8 +302,8 @@ add_newdoc('numpy.core', 'nditer',
     shape : tuple of ints
         Shape tuple, the shape of the iterator.
     value
-        Value of `operands` at current iteration. Normally, this is a
-        tuple of array scalars, but if the flag "external_loop" is used,
+        Value of ``operands`` at current iteration. Normally, this is a
+        tuple of array scalars, but if the flag ``external_loop`` is used,
         it is a tuple of one dimensional arrays.
 
     Notes
@@ -313,12 +314,12 @@ add_newdoc('numpy.core', 'nditer',
     The Python exposure supplies two iteration interfaces, one which follows
     the Python iterator protocol, and another which mirrors the C-style
     do-while pattern.  The native Python approach is better in most cases, but
-    if you need the iterator's coordinates or index, use the C-style pattern.
+    if you need the coordinates or index of an iterator, use the C-style pattern.
 
     Examples
     --------
     Here is how we might write an ``iter_add`` function, using the
-    Python iterator protocol::
+    Python iterator protocol:
 
     >>> def iter_add_py(x, y, out=None):
     ...     addop = np.add
@@ -329,7 +330,7 @@ add_newdoc('numpy.core', 'nditer',
     ...             addop(a, b, out=c)
     ...     return it.operands[2]
 
-    Here is the same function, but following the C-style pattern::
+    Here is the same function, but following the C-style pattern:
 
     >>> def iter_add(x, y, out=None):
     ...    addop = np.add
@@ -341,7 +342,7 @@ add_newdoc('numpy.core', 'nditer',
     ...            it.iternext()
     ...        return it.operands[2]
 
-    Here is an example outer product function::
+    Here is an example outer product function:
 
     >>> def outer_it(x, y, out=None):
     ...     mulop = np.multiply
@@ -361,7 +362,7 @@ add_newdoc('numpy.core', 'nditer',
     array([[1, 2, 3],
            [2, 4, 6]])
 
-    Here is an example function which operates like a "lambda" ufunc::
+    Here is an example function which operates like a "lambda" ufunc:
 
     >>> def luf(lamdaexpr, *args, **kwargs):
     ...    '''luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)'''
@@ -2031,21 +2032,27 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('ctypes',
     as well as documented private attributes):
 
     .. autoattribute:: numpy.core._internal._ctypes.data
+        :noindex:
 
     .. autoattribute:: numpy.core._internal._ctypes.shape
+        :noindex:
 
     .. autoattribute:: numpy.core._internal._ctypes.strides
+        :noindex:
 
     .. automethod:: numpy.core._internal._ctypes.data_as
+        :noindex:
 
     .. automethod:: numpy.core._internal._ctypes.shape_as
+        :noindex:
 
     .. automethod:: numpy.core._internal._ctypes.strides_as
+        :noindex:
 
     If the ctypes module is not available, then the ctypes attribute
     of array objects still returns something useful, but ctypes objects
     are not returned and errors may be raised instead. In particular,
-    the object will still have the as parameter attribute which will
+    the object will still have the ``as_parameter`` attribute which will
     return an integer equal to the data attribute.
 
     Examples
@@ -4861,7 +4868,7 @@ add_newdoc('numpy.core', 'ufunc', ('reduce',
     out : ndarray, None, or tuple of ndarray and None, optional
         A location into which the result is stored. If not provided or `None`,
         a freshly-allocated array is returned. For consistency with
-        :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
+        ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
         1-element tuple.
 
         .. versionchanged:: 1.13.0
@@ -4978,7 +4985,7 @@ add_newdoc('numpy.core', 'ufunc', ('accumulate',
     out : ndarray, None, or tuple of ndarray and None, optional
         A location into which the result is stored. If not provided or `None`,
         a freshly-allocated array is returned. For consistency with
-        :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
+        ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
         1-element tuple.
 
         .. versionchanged:: 1.13.0
@@ -5060,7 +5067,7 @@ add_newdoc('numpy.core', 'ufunc', ('reduceat',
     out : ndarray, None, or tuple of ndarray and None, optional
         A location into which the result is stored. If not provided or `None`,
         a freshly-allocated array is returned. For consistency with
-        :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a
+        ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
         1-element tuple.
 
         .. versionchanged:: 1.13.0
diff --git a/numpy/core/defchararray.py b/numpy/core/defchararray.py
index 007fc6186..3fd7d14c4 100644
--- a/numpy/core/defchararray.py
+++ b/numpy/core/defchararray.py
@@ -29,7 +29,7 @@ from numpy.compat import asbytes, long
 import numpy
 
 __all__ = [
-    'chararray', 'equal', 'not_equal', 'greater_equal', 'less_equal',
+    'equal', 'not_equal', 'greater_equal', 'less_equal',
     'greater', 'less', 'str_len', 'add', 'multiply', 'mod', 'capitalize',
     'center', 'count', 'decode', 'encode', 'endswith', 'expandtabs',
     'find', 'index', 'isalnum', 'isalpha', 'isdigit', 'islower', 'isspace',
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index cdb6c4bed..04b1e9fae 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -912,6 +912,7 @@ def sort(a, axis=-1, kind='quicksort', order=None):
     data types.
 
     .. versionadded:: 1.17.0
+
     Timsort is added for better performance on already or nearly
     sorted data. On random data timsort is almost identical to
     mergesort. It is now used for stable sort while quicksort is still the
diff --git a/numpy/core/shape_base.py b/numpy/core/shape_base.py
index 08e07bb66..e43519689 100644
--- a/numpy/core/shape_base.py
+++ b/numpy/core/shape_base.py
@@ -347,9 +347,9 @@ def stack(arrays, axis=0, out=None):
     """
     Join a sequence of arrays along a new axis.
 
-    The `axis` parameter specifies the index of the new axis in the dimensions
-    of the result. For example, if ``axis=0`` it will be the first dimension
-    and if ``axis=-1`` it will be the last dimension.
+    The ``axis`` parameter specifies the index of the new axis in the
+    dimensions of the result. For example, if ``axis=0`` it will be the first
+    dimension and if ``axis=-1`` it will be the last dimension.
 
     .. versionadded:: 1.10.0
 
@@ -357,8 +357,10 @@ def stack(arrays, axis=0, out=None):
     ----------
     arrays : sequence of array_like
         Each array must have the same shape.
+
     axis : int, optional
         The axis in the result array along which the input arrays are stacked.
+
     out : ndarray, optional
         If provided, the destination to place the result. The shape must be
         correct, matching that of what stack would have returned if no
diff --git a/numpy/doc/glossary.py b/numpy/doc/glossary.py
index a3707340d..7d1c9a1d5 100644
--- a/numpy/doc/glossary.py
+++ b/numpy/doc/glossary.py
@@ -159,7 +159,7 @@ Glossary
 
    field
        In a :term:`structured data type`, each sub-type is called a `field`.
-       The `field` has a name (a string), a type (any valid :term:`dtype`, and
+       The `field` has a name (a string), a type (any valid dtype, and
        an optional `title`. See :ref:`arrays.dtypes`
 
    Fortran order
@@ -209,6 +209,9 @@ Glossary
          Key 1: b
          Key 2: c
 
+   itemsize
+       The size of the dtype element in bytes.
+
    list
        A Python container that can hold any number of objects or items.
        The items do not have to be of the same type, and can even be
@@ -345,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`
@@ -377,6 +380,20 @@ Glossary
    structured data type
        A data type composed of other datatypes
 
+   subarray data type
+       A :term:`structured data type` may contain a :term:`ndarray` with its
+       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
+       associated :ref:`title <titles>` which is an alias to the name and is
+       commonly used for plotting.
+
    tuple
        A sequence that may contain a variable number of types of any
        kind.  A tuple is immutable, i.e., once constructed it cannot be
@@ -413,8 +430,19 @@ Glossary
          'alpha'
 
    ufunc
-       Universal function.  A fast element-wise array operation.  Examples include
-       ``add``, ``sin`` and ``logical_or``.
+       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 sense,
+       vectorization performs the same operation on multiple elements with
+       fixed strides between them via specialized hardware. Compilers know how
+       to take advantage of well-constructed loops to implement such
+       optimizations. NumPy uses :ref:`vectorization <whatis-vectorization>`
+       to mean any optimization via specialized code performing the same
+       operations on multiple elements, typically achieving speedups by
+       avoiding some of the overhead in looking up and converting the elements.
 
    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 da3a74bd6..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:`sub-array` 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
 ----------------------------
@@ -231,7 +231,7 @@ each field's offset is a multiple of its size and that the itemsize is a
 multiple of the largest field size, and raise an exception if not.
 
 If the offsets of the fields and itemsize of a structured array satisfy the
-alignment conditions, the array will have the ``ALIGNED`` :ref:`flag
+alignment conditions, the array will have the ``ALIGNED`` :attr:`flag
 <numpy.ndarray.flags>` set.
 
 A convenience function :func:`numpy.lib.recfunctions.repack_fields` converts an
@@ -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 :term:`titles` 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
@@ -431,8 +431,9 @@ array, as follows::
 
 Assignment to the view modifies the original array. The view's fields will be
 in the order they were indexed. Note that unlike for single-field indexing, the
-view's dtype has the same itemsize as the original array, and has fields at the
-same offsets as in the original array, and unindexed fields are merely missing.
+dtype of the view has the same itemsize as the original array, and has fields
+at the same offsets as in the original array, and unindexed fields are merely
+missing.
 
 .. warning::
     In Numpy 1.15, indexing an array with a multi-field index returned a copy of
@@ -453,7 +454,7 @@ same offsets as in the original array, and unindexed fields are merely missing.
     Numpy 1.12, and similar code has raised ``FutureWarning`` since 1.7.
 
     In 1.16 a number of functions have been introduced in the
-    :module:`numpy.lib.recfunctions` module to help users account for this
+    :mod:`numpy.lib.recfunctions` module to help users account for this
     change. These are
     :func:`numpy.lib.recfunctions.repack_fields`.
     :func:`numpy.lib.recfunctions.structured_to_unstructured`,
@@ -610,7 +611,7 @@ creating record arrays, see :ref:`record array creation routines
 <routines.array-creation.rec>`.
 
 A record array representation of a structured array can be obtained using the
-appropriate :ref:`view`::
+appropriate `view <numpy-ndarray-view>`_::
 
  >>> arr = np.array([(1, 2., 'Hello'), (2, 3., "World")],
  ...                dtype=[('foo', 'i4'),('bar', 'f4'), ('baz', 'a10')])
diff --git a/numpy/linalg/linalg.py b/numpy/linalg/linalg.py
index 304fce69f..5e6e423a7 100644
--- a/numpy/linalg/linalg.py
+++ b/numpy/linalg/linalg.py
@@ -2621,10 +2621,8 @@ def multi_dot(arrays):
     instead of::
 
     >>> _ = np.dot(np.dot(np.dot(A, B), C), D)
-    ...
     >>> # or
     >>> _ = A.dot(B).dot(C).dot(D)
-    ...
 
     Notes
     -----
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)