Merge pull request #13002 from mattip/doc-warnings2

DOC: reduce warnings when building, and rephrase slightly

1 files changed, 48 insertions, 20 deletions

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