Repository: numpy/numpy

Issue:
DOC : dype attributes docs don't contain examples
The documentation for attributes of `dtype` in the `_add_newdocs.py` can be improved by adding examples, which are currently missing for most of the attributes.


Discussion:

Resolving patch:
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -5385,6 +5385,17 @@
 
     More information is available in the C-API section of the manual.
 
+    Examples
+    --------
+
+    >>> x = np.dtype('i4')
+    >>> x.alignment
+    4
+
+    >>> x = np.dtype(float)
+    >>> x.alignment
+    8
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('byteorder',
@@ -5431,7 +5442,16 @@
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('char',
-    """A unique character code for each of the 21 different built-in types."""))
+    """A unique character code for each of the 21 different built-in types.
+
+    Examples
+    --------
+
+    >>> x = np.dtype(float)
+    >>> x.char
+    'd'
+
+    """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('descr',
     """
@@ -5442,6 +5462,18 @@
 
     Warning: This attribute exists specifically for `__array_interface__`,
     and is not a datatype description compatible with `np.dtype`.
+
+    Examples
+    --------
+
+    >>> x = np.dtype(float)
+    >>> x.descr
+    [('', '<f8')]
+
+    >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
+    >>> dt.descr
+    [('name', '<U16'), ('grades', '<f8', (2,))]
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('fields',
@@ -5482,6 +5514,18 @@
     of these flags is in C-API documentation; they are largely useful
     for user-defined data-types.
 
+    The following example demonstrates that operations on this particular
+    dtype requires Python C-API.
+
+    Examples
+    --------
+
+    >>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
+    >>> x.flags
+    16
+    >>> np.core.multiarray.NEEDS_PYAPI
+    16
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('hasobject',
@@ -5539,6 +5583,7 @@
     field alignment. This flag is sticky, so when combining multiple
     structs together, it is preserved and produces new dtypes which
     are also aligned.
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('itemsize',
@@ -5548,6 +5593,19 @@
     For 18 of the 21 types this number is fixed by the data-type.
     For the flexible data-types, this number can be anything.
 
+    Examples
+    --------
+
+    >>> arr = np.array([[1, 2], [3, 4]])
+    >>> arr.dtype
+    dtype('int64')
+    >>> arr.itemsize
+    8
+
+    >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
+    >>> dt.itemsize
+    80
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('kind',
@@ -5568,6 +5626,19 @@
     V  void
     =  ======================
 
+    Examples
+    --------
+
+    >>> dt = np.dtype('i4')
+    >>> dt.kind
+    'i'
+    >>> dt = np.dtype('f8')
+    >>> dt.kind
+    'f'
+    >>> dt = np.dtype([('field1', 'f8')])
+    >>> dt.kind
+    'V'
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('name',
@@ -5576,6 +5647,16 @@
 
     Un-sized flexible data-type objects do not have this attribute.
 
+    Examples
+    --------
+
+    >>> x = np.dtype(float)
+    >>> x.name
+    'float64'
+    >>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
+    >>> x.name
+    'void640'
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('names',
@@ -5599,6 +5680,17 @@
 
     These are roughly ordered from least-to-most precision.
 
+    Examples
+    --------
+
+    >>> dt = np.dtype(str)
+    >>> dt.num
+    19
+
+    >>> dt = np.dtype(float)
+    >>> dt.num
+    12
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('shape',
@@ -5606,6 +5698,17 @@
     Shape tuple of the sub-array if this data type describes a sub-array,
     and ``()`` otherwise.
 
+    Examples
+    --------
+
+    >>> dt = np.dtype(('i4', 4))
+    >>> dt.shape
+    (4,)
+
+    >>> dt = np.dtype(('i4', (2, 3)))
+    >>> dt.shape
+    (2, 3)
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('ndim',
@@ -5615,6 +5718,20 @@
 
     .. versionadded:: 1.13.0
 
+    Examples
+    --------
+    >>> x = np.dtype(float)
+    >>> x.ndim
+    0
+
+    >>> x = np.dtype((float, 8))
+    >>> x.ndim
+    1
+
+    >>> x = np.dtype(('i4', (3, 4)))
+    >>> x.ndim
+    2
+
     """))
 
 add_newdoc('numpy.core.multiarray', 'dtype', ('str',


Test patch: