Docstring update: numpy.doc

4 files changed, 76 insertions, 144 deletions

diff --git a/numpy/doc/__init__.py b/numpy/doc/__init__.py
index 44eb42441..85c378182 100644
--- a/numpy/doc/__init__.py
+++ b/numpy/doc/__init__.py
@@ -20,7 +20,7 @@ The following topics are available:
 
 You can view them by
 
->>> help(doc.TOPIC)
+>>> help(np.doc.TOPIC)
 
 """ % '\n- '.join([''] + __all__)
 
diff --git a/numpy/doc/broadcasting.py b/numpy/doc/broadcasting.py
index 95e9b67f9..7b6179663 100644
--- a/numpy/doc/broadcasting.py
+++ b/numpy/doc/broadcasting.py
@@ -13,8 +13,9 @@ efficient algorithm implementations. There are, however, cases where
 broadcasting is a bad idea because it leads to inefficient use of memory
 that slows computation.
 
-NumPy operations are usually done element-by-element, which requires two
-arrays to have exactly the same shape::
+NumPy operations are usually done on pairs of arrays on an
+element-by-element basis.  In the simplest case, the two arrays must
+have exactly the same shape, as in the following example:
 
   >>> a = np.array([1.0, 2.0, 3.0])
   >>> b = np.array([2.0, 2.0, 2.0])
@@ -38,9 +39,9 @@ only conceptual.  NumPy is smart enough to use the original scalar value
 without actually making copies, so that broadcasting operations are as
 memory and computationally efficient as possible.
 
-The second example is more effective than the first, since here broadcasting
-moves less memory around during the multiplication (``b`` is a scalar,
-not an array).
+The code in the second example is more efficient than that in the first
+because broadcasting moves less memory around during the multiplication
+(``b`` is a scalar rather than an array).
 
 General Broadcasting Rules
 ==========================
@@ -107,7 +108,7 @@ Here are examples of shapes that do not broadcast::
   B      (1d array):  4 # trailing dimensions do not match
 
   A      (2d array):      2 x 1
-  B      (3d array):  8 x 4 x 3 # second from last dimensions mismatch
+  B      (3d array):  8 x 4 x 3 # second from last dimensions mismatched
 
 An example of broadcasting in practice::
 
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)
 
     """)
diff --git a/numpy/doc/structured_arrays.py b/numpy/doc/structured_arrays.py
index 7bbd0deda..59af4eb57 100644
--- a/numpy/doc/structured_arrays.py
+++ b/numpy/doc/structured_arrays.py
@@ -24,10 +24,9 @@ position we get the second record: ::
  >>> x[1]
  (2,3.,"World")
 
-The interesting aspect is that we can reference the different fields of the
-array simply by indexing the array with the string representing the name of
-the field. In this case the fields have received the default names of 'f0', 'f1'
-and 'f2'.
+Conveniently, one can access any field of the array by indexing using the
+string that names that field. In this case the fields have received the
+default names 'f0', 'f1' and 'f2'.
 
  >>> y = x['f1']
  >>> y
@@ -40,11 +39,11 @@ and 'f2'.
        dtype=[('f0', '>i4'), ('f1', '>f4'), ('f2', '|S10')])
 
 In these examples, y is a simple float array consisting of the 2nd field
-in the record. But it is not a copy of the data in the structured array,
-instead it is a view. It shares exactly the same data. Thus when we updated
-this array by doubling its values, the structured array shows the
-corresponding values as doubled as well. Likewise, if one changes the record,
-the field view changes: ::
+in the record. But, rather than being a copy of the data in the structured
+array, it is a view, i.e., it shares exactly the same memory locations.
+Thus, when we updated this array by doubling its values, the structured
+array shows the corresponding values as doubled as well. Likewise, if one
+changes the record, the field view also changes: ::
 
  >>> x[1] = (-1,-1.,"Master")
  >>> x
@@ -56,19 +55,19 @@ the field view changes: ::
 Defining Structured Arrays
 ==========================
 
-The definition of a structured array is all done through the dtype object.
-There are a **lot** of different ways one can define the fields of a
-record. Some of variants are there to provide backward compatibility with
-Numeric or numarray, or another module, and should not be used except for
-such purposes. These will be so noted. One defines records by specifying
-the structure by 4 general ways, using an argument (as supplied to a dtype
-function keyword or a dtype object constructor itself) in the form of a:
-1) string, 2) tuple, 3) list, or 4) dictionary. Each of these will be briefly
-described.
+One defines a structured array through the dtype object.  There are
+**several** alternative ways to define the fields of a record.  Some of
+these variants provide backward compatibility with Numeric, numarray, or
+another module, and should not be used except for such purposes. These
+will be so noted. One specifies record structure in
+one of four alternative ways, using an argument (as supplied to a dtype
+function keyword or a dtype object constructor itself).  This
+argument must be one of the following: 1) string, 2) tuple, 3) list, or
+4) dictionary.  Each of these is briefly described below.
 
 1) String argument (as used in the above examples).
-In this case, the constructor is expecting a comma
-separated list of type specifiers, optionally with extra shape information.
+In this case, the constructor expects a comma-separated list of type
+specifiers, optionally with extra shape information.
 The type specifiers can take 4 different forms: ::
 
   a) b1, i1, i2, i4, i8, u1, u2, u4, u8, f4, f8, c8, c16, a<n>