Docstring update: doc/source/reference

1 files changed, 87 insertions, 84 deletions

diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index 8096e1497..43f38854e 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -40,23 +40,24 @@ same shapes can still be usefully operated on. Broadcasting can be
 understood by four rules:
 
 1. All input arrays with :attr:`ndim <ndarray.ndim>` smaller than the
-   input array of largest :attr:`ndim <ndarray.ndim>` have 1's
+   input array of largest :attr:`ndim <ndarray.ndim>`, have 1's
    prepended to their shapes.
 
 2. The size in each dimension of the output shape is the maximum of all
-   the input shapes in that dimension.
+   the input sizes in that dimension.
 
-3. An input can be used in the calculation if its shape in a particular
-   dimension either matches the output shape or has value exactly 1.
+3. An input can be used in the calculation if its size in a particular
+   dimension either matches the output size in that dimension, or has
+   value exactly 1.
 
 4. If an input has a dimension size of 1 in its shape, the first data
    entry in that dimension will be used for all calculations along
    that dimension. In other words, the stepping machinery of the
-   :term:`ufunc` will simply not step along that dimension when
-   otherwise needed (the :term:`stride` will be 0 for that dimension).
+   :term:`ufunc` will simply not step along that dimension (the
+   :term:`stride` will be 0 for that dimension).
 
-Broadcasting is used throughout NumPy to decide how to handle non
-equally-shaped arrays; for example all arithmetic operators (``+``,
+Broadcasting is used throughout NumPy to decide how to handle
+disparately shaped arrays; for example, all arithmetic operations (``+``,
 ``-``, ``*``, ...) between :class:`ndarrays <ndarray>` broadcast the
 arrays before operation.
 
@@ -79,7 +80,7 @@ is true:
 .. admonition:: Example
 
    If ``a.shape`` is (5,1), ``b.shape`` is (1,6), ``c.shape`` is (6,)
-   and d.shape is ``()`` so that d is a scalar, then *a*, *b*, *c*,
+   and ``d.shape`` is () so that *d* is a scalar, then *a*, *b*, *c*,
    and *d* are all broadcastable to dimension (5,6); and
 
    - *a* acts like a (5,6) array where ``a[:,0]`` is broadcast to the other
@@ -110,9 +111,9 @@ universal function. The default :obj:`__array_priority__` of the
 ndarray is 0.0, and the default :obj:`__array_priority__` of a subtype
 is 1.0. Matrices have :obj:`__array_priority__` equal to 10.0.
 
-The ufuncs can also all take output arguments. The output will be cast
-if necessary to the provided output array. If a class with an
-:obj:`__array__` method is used for the output, results will be
+All ufuncs can also take output arguments. If necessary, output will
+be cast to the data-type(s) of the provided output array(s). If a class
+with an :obj:`__array__` method is used for the output, results will be
 written to the object returned by :obj:`__array__`. Then, if the class
 also has an :obj:`__array_prepare__` method, it is called so metadata
 may be determined based on the context of the ufunc (the context
@@ -130,13 +131,13 @@ Use of internal buffers
 
 Internally, buffers are used for misaligned data, swapped data, and
 data that has to be converted from one data type to another. The size
-of the internal buffers is settable on a per-thread basis. There can
+of internal buffers is settable on a per-thread basis. There can
 be up to :math:`2 (n_{\mathrm{inputs}} + n_{\mathrm{outputs}})`
 buffers of the specified size created to handle the data from all the
-inputs and outputs of a ufunc. The default size of the buffer is
+inputs and outputs of a ufunc. The default size of a buffer is
 10,000 elements. Whenever buffer-based calculation would be needed,
 but all input arrays are smaller than the buffer size, those
-misbehaved or incorrect typed arrays will be copied before the
+misbehaved or incorrectly-typed arrays will be copied before the
 calculation proceeds. Adjusting the size of the buffer may therefore
 alter the speed at which ufunc calculations of various sorts are
 completed. A simple interface for setting this variable is accessible
@@ -153,7 +154,7 @@ Error handling
 
 .. index:: error handling
 
-Universal functions can trip special floating point status registers
+Universal functions can trip special floating-point status registers
 in your hardware (such as divide-by-zero). If available on your
 platform, these registers will be regularly checked during
 calculation. Error handling is controlled on a per-thread basis,
@@ -181,36 +182,37 @@ The ufunc machinery uses this list to determine which inner loop to
 use for a particular case. You can inspect the :attr:`.types
 <ufunc.types>` attribute for a particular ufunc to see which type
 combinations have a defined inner loop and which output type they
-produce (:ref:`character codes <arrays.scalars.character-codes>` are used in
-that output for brevity).
+produce (:ref:`character codes <arrays.scalars.character-codes>` are used
+in said output for brevity).
 
 Casting must be done on one or more of the inputs whenever the ufunc
 does not have a core loop implementation for the input types provided.
 If an implementation for the input types cannot be found, then the
 algorithm searches for an implementation with a type signature to
 which all of the inputs can be cast "safely." The first one it finds
-in its internal list of loops is selected and performed with types
-cast. Recall that internal copies during ufuncs (even for casting) are
-limited to the size of an internal buffer which is user settable.
+in its internal list of loops is selected and performed, after all
+necessary type casting. Recall that internal copies during ufuncs (even
+for casting) are limited to the size of an internal buffer (which is user
+settable).
 
 .. note::
 
     Universal functions in NumPy are flexible enough to have mixed type
     signatures. Thus, for example, a universal function could be defined
-    that works with floating point and integer values. See :func:`ldexp`
+    that works with floating-point and integer values. See :func:`ldexp`
     for an example.
 
 By the above description, the casting rules are essentially
 implemented by the question of when a data type can be cast "safely"
 to another data type. The answer to this question can be determined in
 Python with a function call: :func:`can_cast(fromtype, totype)
-<can_cast>`. Figure shows the results of this call for my 32-bit
-system on the 21 internally supported types. You can generate this
-table for your system with code shown in that Figure.
+<can_cast>`. The Figure below shows the results of this call for
+the 21 internally supported types on the author's 32-bit system. You
+can generate this table for your system with the code given in the Figure.
 
 .. admonition:: Figure
 
-    Code segment showing the can cast safely table for a 32-bit system.
+    Code segment showing the "can cast safely" table for a 32-bit system.
 
     >>> def print_table(ntypes):
     ...     print 'X',
@@ -250,14 +252,14 @@ table for your system with code shown in that Figure.
 You should note that, while included in the table for completeness,
 the 'S', 'U', and 'V' types cannot be operated on by ufuncs. Also,
 note that on a 64-bit system the integer types may have different
-sizes resulting in a slightly altered table.
+sizes, resulting in a slightly altered table.
 
 Mixed scalar-array operations use a different set of casting rules
-that ensure that a scalar cannot upcast an array unless the scalar is
-of a fundamentally different kind of data (*i.e.* under a different
-hierachy in the data type hierarchy) than the array.  This rule
-enables you to use scalar constants in your code (which as Python
-types are interpreted accordingly in ufuncs) without worrying about
+that ensure that a scalar cannot "upcast" an array unless the scalar is
+of a fundamentally different kind of data (*i.e.*, under a different
+hierarchy in the data-type hierarchy) than the array.  This rule
+enables you to use scalar constants in your code (which, as Python
+types, are interpreted accordingly in ufuncs) without worrying about
 whether the precision of the scalar constant will cause upcasting on
 your large (small precision) array.
 
@@ -269,7 +271,7 @@ Optional keyword arguments
 --------------------------
 
 All ufuncs take optional keyword arguments. These represent rather
-advanced usage and will likely not be used by most users.
+advanced usage and will not typically be used by most Numpy users.
 
 .. index::
    pair: ufunc; keyword arguments
@@ -278,23 +280,24 @@ advanced usage and will likely not be used by most users.
 
     Either a data-type, a tuple of data-types, or a special signature
     string indicating the input and output types of a ufunc. This argument
-    allows you to specify a specific signature for a the 1-d loop to use
+    allows you to provide a specific signature for the 1-d loop to use
     in the underlying calculation. If the loop specified does not exist
-    for the ufunc, then a TypeError is raised. Normally a suitable loop is
+    for the ufunc, then a TypeError is raised. Normally, a suitable loop is
     found automatically by comparing the input types with what is
     available and searching for a loop with data-types to which all inputs
-    can be cast safely. This key-word argument lets you by-pass that
-    search and choose a loop you want. A list of available signatures is
-    available in the **types** attribute of the ufunc object.
+    can be cast safely. This keyword argument lets you bypass that
+    search and choose a particular loop. A list of available signatures is
+    provided by the **types** attribute of the ufunc object.
 
 *extobj*
 
     a list of length 1, 2, or 3 specifying the ufunc buffer-size, the
     error mode integer, and the error call-back function. Normally, these
-    values are looked-up in a thread-specific dictionary. Passing them
-    here bypasses that look-up and uses the low-level specification
-    provided for the error-mode. This may be useful as an optimization for
-    calculations requiring lots of ufuncs on small arrays in a loop.
+    values are looked up in a thread-specific dictionary. Passing them
+    here circumvents that look up and uses the low-level specification
+    provided for the error mode. This may be useful, for example, as an
+    optimization for calculations requiring many ufunc calls on small arrays
+    in a loop.
 
 
 Attributes
@@ -329,28 +332,27 @@ possess. None of the attributes can be set.
 Methods
 -------
 
-All ufuncs have 4 methods. However, these methods only make sense on
+All ufuncs have four methods. However, these methods only make sense on
 ufuncs that take two input arguments and return one output argument.
 Attempting to call these methods on other ufuncs will cause a
-:exc:`ValueError` . The reduce-like methods all take an *axis* keyword
-and a *dtype* keyword, and the arrays must all have dimension >=
-1. The *axis* keyword specifies which axis of the array the reduction
-will take place over and may be negative, but must be an integer. The
+:exc:`ValueError`. The reduce-like methods all take an *axis* keyword
+and a *dtype* keyword, and the arrays must all have dimension >= 1.
+The *axis* keyword specifies the axis of the array over which the reduction
+will take place and may be negative, but must be an integer. The
 *dtype* keyword allows you to manage a very common problem that arises
 when naively using :ref:`{op}.reduce <ufunc.reduce>`. Sometimes you may
 have an array of a certain data type and wish to add up all of its
 elements, but the result does not fit into the data type of the
 array. This commonly happens if you have an array of single-byte
-integers. The *dtype* keyword allows you to alter the data type that the
-reduction takes place over (and therefore the type of the
-output). Thus, you can ensure that the output is a data type with
-large-enough precision to handle your output. The responsibility of
-altering the reduce type is mostly up to you. There is one exception:
-if no *dtype* is given for a reduction on the "add" or "multiply"
-operations, then if the input type is an integer (or boolean) data-
-type and smaller than the size of the :class:`int_` data type, it will
-be internally upcast to the :class:`int_` (or :class:`uint`) data
-type.
+integers. The *dtype* keyword allows you to alter the data type over which
+the reduction takes place (and therefore the type of the output). Thus,
+you can ensure that the output is a data type with precision large enough
+to handle your output. The responsibility of altering the reduce type is
+mostly up to you. There is one exception: if no *dtype* is given for a
+reduction on the "add" or "multiply" operations, then if the input type is
+an integer (or Boolean) data-type and smaller than the size of the
+:class:`int_` data type, it will be internally upcast to the :class:`int_`
+(or :class:`uint`) data-type.
 
 .. index::
    pair: ufunc; methods
@@ -366,10 +368,10 @@ type.
 
 .. warning::
 
-    A reduce-like operation on an array with a data type that has
-    range "too small "to handle the result will silently wrap. You
-    should use dtype to increase the data type over which reduction
-    takes place.
+    A reduce-like operation on an array with a data-type that has a
+    range "too small" to handle the result will silently wrap. One
+    should use `dtype` to increase the size of the data-type over which
+    reduction takes place.
 
 
 Available ufuncs
@@ -378,11 +380,11 @@ Available ufuncs
 There are currently more than 60 universal functions defined in
 :mod:`numpy` on one or more types, covering a wide variety of
 operations. Some of these ufuncs are called automatically on arrays
-when the relevant infix notation is used (*e.g.* :func:`add(a, b) <add>`
+when the relevant infix notation is used (*e.g.*, :func:`add(a, b) <add>`
 is called internally when ``a + b`` is written and *a* or *b* is an
-:class:`ndarray`). Nonetheless, you may still want to use the ufunc
+:class:`ndarray`). Nevertheless, you may still want to use the ufunc
 call in order to use the optional output argument(s) to place the
-output(s) in an object (or in objects) of your choice.
+output(s) in an object (or objects) of your choice.
 
 Recall that each ufunc operates element-by-element. Therefore, each
 ufunc will be described as if acting on a set of scalar inputs to
@@ -433,9 +435,10 @@ Math operations
     for large calculations. If your arrays are large, complicated
     expressions can take longer than absolutely necessary due to the
     creation and (later) destruction of temporary calculation
-    spaces. For example, the expression ``G=a*b+c`` is equivalent to
-    ``t1=A*B; G=T1+C; del t1``. It will be more quickly executed as
-    ``G=A*B; add(G,C,G)`` which is the same as ``G=A*B; G+=C``.
+    spaces. For example, the expression ``G = a * b + c`` is equivalent to
+    ``t1 = A * B; G = T1 + C; del t1``. It will be more quickly executed
+    as ``G = A * B; add(G, C, G)`` which is the same as
+    ``G = A * B; G += C``.
 
 
 Trigonometric functions
@@ -465,8 +468,8 @@ The ratio of degrees to radians is :math:`180^{\circ}/\pi.`
 Bit-twiddling functions
 -----------------------
 
-These function all need integer arguments and they maniuplate the bit-
-pattern of those arguments.
+These function all require integer arguments and they manipulate the
+bit-pattern of those arguments.
 
 .. autosummary::
 
@@ -494,7 +497,7 @@ Comparison functions
     Do not use the Python keywords ``and`` and ``or`` to combine
     logical array expressions. These keywords will test the truth
     value of the entire array (not element-by-element as you might
-    expect). Use the bitwise operators: & and \| instead.
+    expect). Use the bitwise operators & and \| instead.
 
 .. autosummary::
 
@@ -505,11 +508,11 @@ Comparison functions
 
 .. warning::
 
-    The Bitwise operators (& and \|) are the proper way to combine
-    element-by-element array comparisons. Be sure to understand the
-    operator precedence: (a>2) & (a<5) is the proper syntax because a>2 &
-    a<5 will result in an error due to the fact that 2 & a is evaluated
-    first.
+    The bit-wise operators & and \| are the proper way to perform
+    element-by-element array comparisons. Be sure you understand the
+    operator precedence: ``(a > 2) & (a < 5)`` is the proper syntax because
+    ``a > 2 & a < 5`` will result in an error due to the fact that ``2 & a``
+    is evaluated first.
 
 .. autosummary::
 
@@ -517,9 +520,9 @@ Comparison functions
 
 .. tip::
 
-    The Python function max() will find the maximum over a one-dimensional
+    The Python function ``max()`` will find the maximum over a one-dimensional
     array, but it will do so using a slower sequence interface. The reduce
-    method of the maximum ufunc is much faster. Also, the max() method
+    method of the maximum ufunc is much faster. Also, the ``max()`` method
     will not give answers you might expect for arrays with greater than
     one dimension. The reduce method of minimum also allows you to compute
     a total minimum over an array.
@@ -530,13 +533,13 @@ Comparison functions
 
 .. warning::
 
-    the behavior of maximum(a,b) is than that of max(a,b). As a ufunc,
-    maximum(a,b) performs an element-by-element comparison of a and b and
-    chooses each element of the result according to which element in the
-    two arrays is larger. In contrast, max(a,b) treats the objects a and b
-    as a whole, looks at the (total) truth value of a>b and uses it to
-    return either a or b (as a whole). A similar difference exists between
-    minimum(a,b) and min(a,b).
+    the behavior of ``maximum(a, b)`` is different than that of ``max(a, b)``.
+    As a ufunc, ``maximum(a, b)`` performs an element-by-element comparison
+    of `a` and `b` and chooses each element of the result according to which
+    element in the two arrays is larger. In contrast, ``max(a, b)`` treats
+    the objects `a` and `b` as a whole, looks at the (total) truth value of
+    ``a > b`` and uses it to return either `a` or `b` (as a whole). A similar
+    difference exists between ``minimum(a, b)`` and ``min(a, b)``.
 
 
 Floating functions