Docstring update: numpy.doc

1 files changed, 49 insertions, 117 deletions

diff --git a/numpy/doc/constants.py b/numpy/doc/constants.py
index 154c74621..7a9105667 100644
--- a/numpy/doc/constants.py
+++ b/numpy/doc/constants.py
@@ -18,19 +18,12 @@ add_newdoc('numpy', 'Inf',
     """
     IEEE 754 floating point representation of (positive) infinity.
 
-    Returns
-    -------
-    y : A floating point representation of positive infinity.
-
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-    Also that positive infinity is not equivalent to negative infinity. But
-    infinity is equivalent to positive infinity.
+    Use `inf` because `Inf`, `Infinity`, `PINF` and `infty` are aliases for
+    `inf`. For more details, see `inf`.
 
-    Use numpy.inf because Inf, Infinity, PINF, infty are equivalent
-    definitions of numpy.inf.
+    See Also
+    --------
+    inf
 
     """)
 
@@ -38,19 +31,12 @@ add_newdoc('numpy', 'Infinity',
     """
     IEEE 754 floating point representation of (positive) infinity.
 
-    Returns
-    -------
-    y : A floating point representation of positive infinity.
-
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-    Also that positive infinity is not equivalent to negative infinity. But
-    infinity is equivalent to positive infinity.
+    Use `inf` because `Inf`, `Infinity`, `PINF` and `infty` are aliases for
+    `inf`. For more details, see `inf`.
 
-    Use numpy.inf because Inf, Infinity, PINF, infty are equivalent
-    definitions of numpy.inf.
+    See Also
+    --------
+    inf
 
     """)
 
@@ -58,33 +44,12 @@ add_newdoc('numpy', 'NAN',
     """
     IEEE 754 floating point representation of Not a Number (NaN).
 
-    Returns
-    -------
-    y : A floating point representation of Not a Number.
+    `NaN` and `NAN` are equivalent definitions of `nan`. Please use
+    `nan` instead of `NAN`.
 
     See Also
     --------
-    isnan: Shows which elements are Not a Number.
-
-    isfinite: Shows which elements are finite (not one of Not a Number, positive infinity and negative infinity)
-
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-
-    NaN and NAN are equivalent definitions of numpy.nan. Please use
-    numpy.nan instead of numpy.NAN.
-
-
-    Examples
-    --------
-    >>> np.NAN
-    nan
-    >>> np.log(-1)
     nan
-    >>> np.log([-1, 1, 2])
-    array([        NaN,  0.        ,  0.69314718])
 
     """)
 
@@ -94,7 +59,8 @@ add_newdoc('numpy', 'NINF',
 
     Returns
     -------
-    y : A floating point representation of negative infinity.
+    y : float
+        A floating point representation of negative infinity.
 
     See Also
     --------
@@ -116,7 +82,6 @@ add_newdoc('numpy', 'NINF',
     Also that positive infinity is not equivalent to negative infinity. But
     infinity is equivalent to positive infinity.
 
-
     Examples
     --------
     >>> np.NINF
@@ -132,7 +97,8 @@ add_newdoc('numpy', 'NZERO',
 
     Returns
     -------
-    y : A floating point representation of negative zero.
+    y : float
+        A floating point representation of negative zero.
 
     See Also
     --------
@@ -154,13 +120,13 @@ add_newdoc('numpy', 'NZERO',
     Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
     (IEEE 754). Negative zero is considered to be a finite number.
 
-
     Examples
     --------
     >>> np.NZERO
     -0.0
     >>> np.PZERO
     0.0
+
     >>> np.isfinite([np.NZERO])
     array([ True], dtype=bool)
     >>> np.isnan([np.NZERO])
@@ -174,34 +140,12 @@ add_newdoc('numpy', 'NaN',
     """
     IEEE 754 floating point representation of Not a Number (NaN).
 
-    Returns
-    -------
-    y : A floating point representation of Not a Number.
+    `NaN` and `NAN` are equivalent definitions of `nan`. Please use
+    `nan` instead of `NaN`.
 
     See Also
     --------
-
-    isnan : Shows which elements are Not a Number.
-
-    isfinite : Shows which elements are finite (not one of Not a Number, positive infinity and negative infinity)
-
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-
-    NaN and NAN are equivalent definitions of numpy.nan. Please use
-    numpy.nan instead of numpy.NaN.
-
-
-    Examples
-    --------
-    >>> np.NaN
-    nan
-    >>> np.log(-1)
     nan
-    >>> np.log([-1, 1, 2])
-    array([        NaN,  0.        ,  0.69314718])
 
     """)
 
@@ -209,19 +153,12 @@ add_newdoc('numpy', 'PINF',
     """
     IEEE 754 floating point representation of (positive) infinity.
 
-    Returns
-    -------
-    y : A floating point representation of positive infinity.
+    Use `inf` because `Inf`, `Infinity`, `PINF` and `infty` are aliases for
+    `inf`. For more details, see `inf`.
 
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-    Also that positive infinity is not equivalent to negative infinity. But
-    infinity is equivalent to positive infinity.
-
-    Use numpy.inf because Inf, Infinity, PINF, infty are equivalent
-    definitions of numpy.inf.
+    See Also
+    --------
+    inf
 
     """)
 
@@ -231,7 +168,8 @@ add_newdoc('numpy', 'PZERO',
 
     Returns
     -------
-    y : A floating point representation of positive zero.
+    y : float
+        A floating point representation of positive zero.
 
     See Also
     --------
@@ -251,8 +189,7 @@ add_newdoc('numpy', 'PZERO',
     Notes
     -----
     Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754).
-
+    (IEEE 754). Positive zero is considered to be a finite number.
 
     Examples
     --------
@@ -260,6 +197,7 @@ add_newdoc('numpy', 'PZERO',
     0.0
     >>> np.NZERO
     -0.0
+
     >>> np.isfinite([np.PZERO])
     array([ True], dtype=bool)
     >>> np.isnan([np.PZERO])
@@ -292,7 +230,8 @@ add_newdoc('numpy', 'inf',
 
     Returns
     -------
-    y : A floating point representation of positive infinity.
+    y : float
+        A floating point representation of positive infinity.
 
     See Also
     --------
@@ -314,14 +253,13 @@ add_newdoc('numpy', 'inf',
     Also that positive infinity is not equivalent to negative infinity. But
     infinity is equivalent to positive infinity.
 
-    Inf, Infinity, PINF, infty are equivalent definitions of numpy.inf.
-
+    `Inf`, `Infinity`, `PINF` and `infty` are aliases for `inf`.
 
     Examples
     --------
     >>> np.inf
     inf
-    >>> np.array([1])/0.
+    >>> np.array([1]) / 0.
     array([ Inf])
 
     """)
@@ -330,19 +268,12 @@ add_newdoc('numpy', 'infty',
     """
     IEEE 754 floating point representation of (positive) infinity.
 
-    Returns
-    -------
-    y : A floating point representation of positive infinity.
+    Use `inf` because `Inf`, `Infinity`, `PINF` and `infty` are aliases for
+    `inf`. For more details, see `inf`.
 
-    Notes
-    -----
-    Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
-    (IEEE 754). This means that Not a Number is not equivalent to infinity.
-    Also that positive infinity is not equivalent to negative infinity. But
-    infinity is equivalent to positive infinity.
-
-    Use numpy.inf because Inf, Infinity, PINF, infty are equivalent
-    definitions of numpy.inf.
+    See Also
+    --------
+    inf
 
     """)
 
@@ -365,8 +296,7 @@ add_newdoc('numpy', 'nan',
     Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic
     (IEEE 754). This means that Not a Number is not equivalent to infinity.
 
-    NaN and NAN are equivalent definitions of numpy.nan.
-
+    `NaN` and `NAN` are aliases of `nan`.
 
     Examples
     --------
@@ -381,6 +311,8 @@ add_newdoc('numpy', 'nan',
 
 add_newdoc('numpy', 'newaxis',
     """
+    A convenient alias for None, useful for indexing arrays.
+
     See Also
     --------
     `numpy.doc.indexing`
@@ -392,36 +324,36 @@ add_newdoc('numpy', 'newaxis',
     >>> x = np.arange(3)
     >>> x
     array([0, 1, 2])
-    >>> x[:,newaxis]
+    >>> x[:, newaxis]
     array([[0],
     [1],
     [2]])
-    >>> x[:,newaxis,newaxis]
+    >>> x[:, newaxis, newaxis]
     array([[[0]],
     [[1]],
     [[2]]])
-    >>> x[:,newaxis] * x
+    >>> x[:, newaxis] * x
     array([[0, 0, 0],
     [0, 1, 2],
     [0, 2, 4]])
 
-    Outer product, same as outer(x,y):
+    Outer product, same as ``outer(x, y)``:
 
-    >>> y = np.arange(3,6)
-    >>> x[:,newaxis] * y
+    >>> y = np.arange(3, 6)
+    >>> x[:, newaxis] * y
     array([[ 0,  0,  0],
     [ 3,  4,  5],
     [ 6,  8, 10]])
 
-    x[newaxis,:] is equivalent to x[newaxis] and x[None]:
+    ``x[newaxis, :]`` is equivalent to ``x[newaxis]`` and ``x[None]``:
 
-    >>> x[newaxis,:].shape
+    >>> x[newaxis, :].shape
     (1, 3)
     >>> x[newaxis].shape
     (1, 3)
     >>> x[None].shape
     (1, 3)
-    >>> x[:,newaxis].shape
+    >>> x[:, newaxis].shape
     (3, 1)
 
     """)