Docstring update: doc/source/reference

8 files changed, 114 insertions, 102 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index f9abfbafa..9e94d5c4d 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -227,6 +227,11 @@ Character arrays (:mod:`numpy.char`)
 .. index::
    single: character arrays
 
+.. note::
+   The chararray module exists for backwards compatibility with Numarray,
+   it is not recommended for new development. If one needs arrays of
+   strings, use arrays of `dtype` object.
+
 These are enhanced arrays of either :class:`string` type or
 :class:`unicode_` type.  These arrays inherit from the
 :class:`ndarray`, but specially-define the operations ``+``, ``*``,
diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst
index 75daf2a08..62e22146a 100644
--- a/doc/source/reference/arrays.scalars.rst
+++ b/doc/source/reference/arrays.scalars.rst
@@ -41,7 +41,7 @@ of the flexible itemsize array types (:class:`string`,
    pointer for the platform. All the number types can be obtained
    using bit-width names as well.
 
-.. [#] However, array scalars are immutable, so that none of the array
+.. [#] However, array scalars are immutable, so none of the array
        scalar attributes are settable.
 
 .. _arrays.scalars.character-codes:
@@ -91,7 +91,7 @@ Python Boolean scalar.
 
 .. tip:: The default data type in Numpy is :class:`float_`.
 
-In the tables below, ``platform?`` means that the type may not
+In the tables below, ``platform?`` means that the type may not be
 available on all platforms. Compatibility with different C or Python
 types is indicated: two types are compatible if their data is of the
 same size and interpreted in the same way.
@@ -144,7 +144,7 @@ Floating-point numbers:
 :class:`longfloat`   compatible: C long float       ``'g'``
 :class:`float32`     32 bits
 :class:`float64`     64 bits
-:class:`float96`     92 bits, platform?
+:class:`float96`     96 bits, platform?
 :class:`float128`    128 bits, platform?
 ===================  =============================  ===============
 
@@ -171,7 +171,7 @@ Any Python object:
 .. note::
 
    The data actually stored in :term:`object arrays <object array>`
-   (*i.e.* arrays having dtype :class:`object_`) are references to
+   (*i.e.*, arrays having dtype :class:`object_`) are references to
    Python objects, not the objects themselves. Hence, object arrays
    behave more like usual Python :class:`lists <list>`, in the sense
    that their contents need not be of the same Python type.
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 8ce362079..3716fa16b 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -1386,11 +1386,9 @@ Shape Manipulation
     (unless refcheck is 0) not be referenced by any other array. A
     reference to the new array is returned. The fortran argument can
     be :cdata:`NPY_ANYORDER`, :cdata:`NPY_CORDER`, or
-    :cdata:`NPY_FORTRANORDER`. This argument is used if the number of
-    dimension is (or is being resized to be) greater than 2. It
-    currently has no effect. Eventually it could be used to determine
-    how the resize operation should view the data when constructing a
-    differently-dimensioned array.
+    :cdata:`NPY_FORTRANORDER`. It currently has no effect. Eventually
+    it could be used to determine how the resize operation should view
+    the data when constructing a differently-dimensioned array.
 
 .. cfunction:: PyObject* PyArray_Transpose(PyArrayObject* self, PyArray_Dims* permute)
 
@@ -2457,7 +2455,7 @@ ABI incompatibility is automatically detected in every numpy's version. API
 incompatibility detection was added in numpy 1.4.0. If you want to supported
 many different numpy versions with one extension binary, you have to build your
 extension with the lowest NPY_FEATURE_VERSION as possible.
-      
+
 .. cfunction:: unsigned int PyArray_GetNDArrayCVersion(void)
 
     This just returns the value :cdata:`NPY_VERSION`. :cdata:`NPY_VERSION`
diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst
index 6a6a0dff0..fc8b5b6b1 100644
--- a/doc/source/reference/c-api.ufunc.rst
+++ b/doc/source/reference/c-api.ufunc.rst
@@ -106,7 +106,13 @@ Functions
         XXX: Undocumented
 
     :param name:
-        The name for the ufunc.
+        The name for the ufunc.  Specifying a name of 'add' or
+        'multiply' enables a special behavior for  integer-typed
+        reductions when no dtype is given.  If the input type is an
+        integer (or boolean) data type smaller than the size of the int_
+        data type, it will be internally upcast to the int_ (or uint)
+        data type.
+
 
     :param doc:
         Allows passing in a documentation string to be stored with the
diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst
index 9f38036c5..fd1fd7ae6 100644
--- a/doc/source/reference/maskedarray.baseclass.rst
+++ b/doc/source/reference/maskedarray.baseclass.rst
@@ -1,4 +1,3 @@
-
 .. currentmodule:: numpy.ma
 
 
@@ -50,7 +49,7 @@ The :class:`MaskedArray` class
 
 .. class:: MaskedArray
 
-   A subclass of :class:`~numpy.ndarray` designed to manipulate numerical array with missing data.
+   A subclass of :class:`~numpy.ndarray` designed to manipulate numerical arrays with missing data.
 
 
 
@@ -107,7 +106,7 @@ Attributes and properties of masked arrays
 
    Returns the value used to fill the invalid entries of a masked array.
    The value is either a scalar (if the masked array has no named fields),
-   or a 0d-ndarray with the same :attr:`dtype` as the masked array if it has
+   or a 0-D ndarray with the same :attr:`dtype` as the masked array if it has
    named fields.
 
    The default filling value depends on the datatype of the array:
@@ -225,9 +224,9 @@ replaced with ``n`` integers which will be interpreted as an n-tuple.
 Item selection and manipulation
 -------------------------------
 
-For array methods that take an *axis* keyword, it defaults to
-:const:`None`. If axis is *None*, then the array is treated as a 1-D
-array. Any other value for *axis* represents the dimension along which
+For array methods that take an *axis* keyword, it defaults to `None`.
+If axis is *None*, then the array is treated as a 1-D array.
+Any other value for *axis* represents the dimension along which
 the operation should proceed.
 
 .. autosummary::
@@ -461,4 +460,3 @@ Counting the missing elements
    :toctree: generated/
 
    MaskedArray.count
-
diff --git a/doc/source/reference/routines.array-creation.rst b/doc/source/reference/routines.array-creation.rst
index 468ab8aa4..4eabb8ec7 100644
--- a/doc/source/reference/routines.array-creation.rst
+++ b/doc/source/reference/routines.array-creation.rst
@@ -36,6 +36,7 @@ From existing data
    fromfile
    fromfunction
    fromiter
+   fromstring
    loadtxt
 
 .. _routines.array-creation.rec:
diff --git a/doc/source/reference/routines.io.rst b/doc/source/reference/routines.io.rst
index 5da0bebf2..1293acb48 100644
--- a/doc/source/reference/routines.io.rst
+++ b/doc/source/reference/routines.io.rst
@@ -19,6 +19,7 @@ Text files
 
    loadtxt
    savetxt
+   genfromtxt
    fromregex
    fromstring
    ndarray.tofile
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