DOC: add a few more wiki edits, and move umath docs to correct place.

4 files changed, 266 insertions, 255 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 187180c5a..1cbf27c7d 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -4048,253 +4048,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
 
 ##############################################################################
 #
-# umath functions
-#
-##############################################################################
-
-add_newdoc('numpy.core.umath', 'frexp',
-    """
-    Return normalized fraction and exponent of 2 of input array, element-wise.
-
-    Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``.
-
-    Parameters
-    ----------
-    x : array_like
-        Input array.
-
-    Returns
-    -------
-    (out1, out2) : tuple of ndarrays, (float, int)
-        `out1` is a float array with values between -1 and 1.
-        `out2` is an int array which represent the exponent of 2.
-
-    See Also
-    --------
-    ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.
-
-    Notes
-    -----
-    Complex dtypes are not supported, they will raise a TypeError.
-
-    Examples
-    --------
-    >>> x = np.arange(9)
-    >>> y1, y2 = np.frexp(x)
-    >>> y1
-    array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,
-            0.5  ])
-    >>> y2
-    array([0, 1, 2, 2, 3, 3, 3, 3, 4])
-    >>> y1 * 2**y2
-    array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])
-
-    """)
-
-add_newdoc('numpy.core.umath', 'frompyfunc',
-    """
-    frompyfunc(func, nin, nout)
-
-    Takes an arbitrary Python function and returns a Numpy ufunc.
-
-    Can be used, for example, to add broadcasting to a built-in Python
-    function (see Examples section).
-
-    Parameters
-    ----------
-    func : Python function object
-        An arbitrary Python function.
-    nin : int
-        The number of input arguments.
-    nout : int
-        The number of objects returned by `func`.
-
-    Returns
-    -------
-    out : ufunc
-        Returns a Numpy universal function (``ufunc``) object.
-
-    Notes
-    -----
-    The returned ufunc always returns PyObject arrays.
-
-    Examples
-    --------
-    Use frompyfunc to add broadcasting to the Python function ``oct``:
-
-    >>> oct_array = np.frompyfunc(oct, 1, 1)
-    >>> oct_array(np.array((10, 30, 100)))
-    array([012, 036, 0144], dtype=object)
-    >>> np.array((oct(10), oct(30), oct(100))) # for comparison
-    array(['012', '036', '0144'],
-          dtype='|S4')
-
-    """)
-
-add_newdoc('numpy.core.umath', 'ldexp',
-    """
-    Compute y = x1 * 2**x2.
-
-    Parameters
-    ----------
-    x1 : array_like
-        The array of multipliers.
-    x2 : array_like
-        The array of exponents.
-
-    Returns
-    -------
-    y : array_like
-        The output array, the result of ``x1 * 2**x2``.
-
-    See Also
-    --------
-    frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`.
-
-    Notes
-    -----
-    Complex dtypes are not supported, they will raise a TypeError.
-
-    `ldexp` is useful as the inverse of `frexp`, if used by itself it is
-    more clear to simply use the expression ``x1 * 2**x2``.
-
-    Examples
-    --------
-    >>> np.ldexp(5, np.arange(4))
-    array([  5.,  10.,  20.,  40.], dtype=float32)
-
-    >>> x = np.arange(6)
-    >>> np.ldexp(*np.frexp(x))
-    array([ 0.,  1.,  2.,  3.,  4.,  5.])
-
-    """)
-
-add_newdoc('numpy.core.umath', 'geterrobj',
-    """
-    geterrobj()
-
-    Return the current object that defines floating-point error handling.
-
-    The error object contains all information that defines the error handling
-    behavior in Numpy. `geterrobj` is used internally by the other
-    functions that get and set error handling behavior (`geterr`, `seterr`,
-    `geterrcall`, `seterrcall`).
-
-    Returns
-    -------
-    errobj : list
-        The error object, a list containing three elements:
-        [internal numpy buffer size, error mask, error callback function].
-
-        The error mask is a single integer that holds the treatment information
-        on all four floating point errors. The information for each error type
-        is contained in three bits of the integer. If we print it in base 8, we
-        can see what treatment is set for "invalid", "under", "over", and
-        "divide" (in that order). The printed string can be interpreted with
-
-        * 0 : 'ignore'
-        * 1 : 'warn'
-        * 2 : 'raise'
-        * 3 : 'call'
-        * 4 : 'print'
-        * 5 : 'log'
-
-    See Also
-    --------
-    seterrobj, seterr, geterr, seterrcall, geterrcall
-    getbufsize, setbufsize
-
-    Notes
-    -----
-    For complete documentation of the types of floating-point exceptions and
-    treatment options, see `seterr`.
-
-    Examples
-    --------
-    >>> np.geterrobj()  # first get the defaults
-    [10000, 0, None]
-
-    >>> def err_handler(type, flag):
-    ...     print "Floating point error (%s), with flag %s" % (type, flag)
-    ...
-    >>> old_bufsize = np.setbufsize(20000)
-    >>> old_err = np.seterr(divide='raise')
-    >>> old_handler = np.seterrcall(err_handler)
-    >>> np.geterrobj()
-    [20000, 2, <function err_handler at 0x91dcaac>]
-
-    >>> old_err = np.seterr(all='ignore')
-    >>> np.base_repr(np.geterrobj()[1], 8)
-    '0'
-    >>> old_err = np.seterr(divide='warn', over='log', under='call',
-                            invalid='print')
-    >>> np.base_repr(np.geterrobj()[1], 8)
-    '4351'
-
-    """)
-
-add_newdoc('numpy.core.umath', 'seterrobj',
-    """
-    seterrobj(errobj)
-
-    Set the object that defines floating-point error handling.
-
-    The error object contains all information that defines the error handling
-    behavior in Numpy. `seterrobj` is used internally by the other
-    functions that set error handling behavior (`seterr`, `seterrcall`).
-
-    Parameters
-    ----------
-    errobj : list
-        The error object, a list containing three elements:
-        [internal numpy buffer size, error mask, error callback function].
-
-        The error mask is a single integer that holds the treatment information
-        on all four floating point errors. The information for each error type
-        is contained in three bits of the integer. If we print it in base 8, we
-        can see what treatment is set for "invalid", "under", "over", and
-        "divide" (in that order). The printed string can be interpreted with
-
-        * 0 : 'ignore'
-        * 1 : 'warn'
-        * 2 : 'raise'
-        * 3 : 'call'
-        * 4 : 'print'
-        * 5 : 'log'
-
-    See Also
-    --------
-    geterrobj, seterr, geterr, seterrcall, geterrcall
-    getbufsize, setbufsize
-
-    Notes
-    -----
-    For complete documentation of the types of floating-point exceptions and
-    treatment options, see `seterr`.
-
-    Examples
-    --------
-    >>> old_errobj = np.geterrobj()  # first get the defaults
-    >>> old_errobj
-    [10000, 0, None]
-
-    >>> def err_handler(type, flag):
-    ...     print "Floating point error (%s), with flag %s" % (type, flag)
-    ...
-    >>> new_errobj = [20000, 12, err_handler]
-    >>> np.seterrobj(new_errobj)
-    >>> np.base_repr(12, 8)  # int for divide=4 ('print') and over=1 ('warn')
-    '14'
-    >>> np.geterr()
-    {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'}
-    >>> np.geterrcall() is err_handler
-    True
-
-    """)
-
-
-##############################################################################
-#
 # lib._compiled_base functions
 #
 ##############################################################################
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
index 591a898ed..d6db8950e 100644
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -1295,6 +1295,149 @@ add_newdoc('numpy.core.umath', 'fmod',
 
     """)
 
+add_newdoc('numpy.core.umath', 'frexp',
+    """
+    Return normalized fraction and exponent of 2 of input array, element-wise.
+
+    Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``.
+
+    Parameters
+    ----------
+    x : array_like
+        Input array.
+
+    Returns
+    -------
+    (out1, out2) : tuple of ndarrays, (float, int)
+        `out1` is a float array with values between -1 and 1.
+        `out2` is an int array which represent the exponent of 2.
+
+    See Also
+    --------
+    ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.
+
+    Notes
+    -----
+    Complex dtypes are not supported, they will raise a TypeError.
+
+    Examples
+    --------
+    >>> x = np.arange(9)
+    >>> y1, y2 = np.frexp(x)
+    >>> y1
+    array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,
+            0.5  ])
+    >>> y2
+    array([0, 1, 2, 2, 3, 3, 3, 3, 4])
+    >>> y1 * 2**y2
+    array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])
+
+    """)
+
+add_newdoc('numpy.core.umath', 'frompyfunc',
+    """
+    frompyfunc(func, nin, nout)
+
+    Takes an arbitrary Python function and returns a Numpy ufunc.
+
+    Can be used, for example, to add broadcasting to a built-in Python
+    function (see Examples section).
+
+    Parameters
+    ----------
+    func : Python function object
+        An arbitrary Python function.
+    nin : int
+        The number of input arguments.
+    nout : int
+        The number of objects returned by `func`.
+
+    Returns
+    -------
+    out : ufunc
+        Returns a Numpy universal function (``ufunc``) object.
+
+    Notes
+    -----
+    The returned ufunc always returns PyObject arrays.
+
+    Examples
+    --------
+    Use frompyfunc to add broadcasting to the Python function ``oct``:
+
+    >>> oct_array = np.frompyfunc(oct, 1, 1)
+    >>> oct_array(np.array((10, 30, 100)))
+    array([012, 036, 0144], dtype=object)
+    >>> np.array((oct(10), oct(30), oct(100))) # for comparison
+    array(['012', '036', '0144'],
+          dtype='|S4')
+
+    """)
+
+add_newdoc('numpy.core.umath', 'geterrobj',
+    """
+    geterrobj()
+
+    Return the current object that defines floating-point error handling.
+
+    The error object contains all information that defines the error handling
+    behavior in Numpy. `geterrobj` is used internally by the other
+    functions that get and set error handling behavior (`geterr`, `seterr`,
+    `geterrcall`, `seterrcall`).
+
+    Returns
+    -------
+    errobj : list
+        The error object, a list containing three elements:
+        [internal numpy buffer size, error mask, error callback function].
+
+        The error mask is a single integer that holds the treatment information
+        on all four floating point errors. The information for each error type
+        is contained in three bits of the integer. If we print it in base 8, we
+        can see what treatment is set for "invalid", "under", "over", and
+        "divide" (in that order). The printed string can be interpreted with
+
+        * 0 : 'ignore'
+        * 1 : 'warn'
+        * 2 : 'raise'
+        * 3 : 'call'
+        * 4 : 'print'
+        * 5 : 'log'
+
+    See Also
+    --------
+    seterrobj, seterr, geterr, seterrcall, geterrcall
+    getbufsize, setbufsize
+
+    Notes
+    -----
+    For complete documentation of the types of floating-point exceptions and
+    treatment options, see `seterr`.
+
+    Examples
+    --------
+    >>> np.geterrobj()  # first get the defaults
+    [10000, 0, None]
+
+    >>> def err_handler(type, flag):
+    ...     print "Floating point error (%s), with flag %s" % (type, flag)
+    ...
+    >>> old_bufsize = np.setbufsize(20000)
+    >>> old_err = np.seterr(divide='raise')
+    >>> old_handler = np.seterrcall(err_handler)
+    >>> np.geterrobj()
+    [20000, 2, <function err_handler at 0x91dcaac>]
+
+    >>> old_err = np.seterr(all='ignore')
+    >>> np.base_repr(np.geterrobj()[1], 8)
+    '0'
+    >>> old_err = np.seterr(divide='warn', over='log', under='call',
+                            invalid='print')
+    >>> np.base_repr(np.geterrobj()[1], 8)
+    '4351'
+
+    """)
+
 add_newdoc('numpy.core.umath', 'greater',
     """
     Return the truth value of (x1 > x2) element-wise.
@@ -1643,6 +1786,44 @@ add_newdoc('numpy.core.umath', 'isnan',
 
     """)
 
+add_newdoc('numpy.core.umath', 'ldexp',
+    """
+    Compute y = x1 * 2**x2.
+
+    Parameters
+    ----------
+    x1 : array_like
+        The array of multipliers.
+    x2 : array_like
+        The array of exponents.
+
+    Returns
+    -------
+    y : array_like
+        The output array, the result of ``x1 * 2**x2``.
+
+    See Also
+    --------
+    frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`.
+
+    Notes
+    -----
+    Complex dtypes are not supported, they will raise a TypeError.
+
+    `ldexp` is useful as the inverse of `frexp`, if used by itself it is
+    more clear to simply use the expression ``x1 * 2**x2``.
+
+    Examples
+    --------
+    >>> np.ldexp(5, np.arange(4))
+    array([  5.,  10.,  20.,  40.], dtype=float32)
+
+    >>> x = np.arange(6)
+    >>> np.ldexp(*np.frexp(x))
+    array([ 0.,  1.,  2.,  3.,  4.,  5.])
+
+    """)
+
 add_newdoc('numpy.core.umath', 'left_shift',
     """
     Shift the bits of an integer to the left.
@@ -2766,6 +2947,65 @@ add_newdoc('numpy.core.umath', 'rint',
 
     """)
 
+add_newdoc('numpy.core.umath', 'seterrobj',
+    """
+    seterrobj(errobj)
+
+    Set the object that defines floating-point error handling.
+
+    The error object contains all information that defines the error handling
+    behavior in Numpy. `seterrobj` is used internally by the other
+    functions that set error handling behavior (`seterr`, `seterrcall`).
+
+    Parameters
+    ----------
+    errobj : list
+        The error object, a list containing three elements:
+        [internal numpy buffer size, error mask, error callback function].
+
+        The error mask is a single integer that holds the treatment information
+        on all four floating point errors. The information for each error type
+        is contained in three bits of the integer. If we print it in base 8, we
+        can see what treatment is set for "invalid", "under", "over", and
+        "divide" (in that order). The printed string can be interpreted with
+
+        * 0 : 'ignore'
+        * 1 : 'warn'
+        * 2 : 'raise'
+        * 3 : 'call'
+        * 4 : 'print'
+        * 5 : 'log'
+
+    See Also
+    --------
+    geterrobj, seterr, geterr, seterrcall, geterrcall
+    getbufsize, setbufsize
+
+    Notes
+    -----
+    For complete documentation of the types of floating-point exceptions and
+    treatment options, see `seterr`.
+
+    Examples
+    --------
+    >>> old_errobj = np.geterrobj()  # first get the defaults
+    >>> old_errobj
+    [10000, 0, None]
+
+    >>> def err_handler(type, flag):
+    ...     print "Floating point error (%s), with flag %s" % (type, flag)
+    ...
+    >>> new_errobj = [20000, 12, err_handler]
+    >>> np.seterrobj(new_errobj)
+    >>> np.base_repr(12, 8)  # int for divide=4 ('print') and over=1 ('warn')
+    '14'
+    >>> np.geterr()
+    {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'}
+    >>> np.geterrcall() is err_handler
+    True
+
+    """)
+
 add_newdoc('numpy.core.umath', 'sign',
     """
     Returns an element-wise indication of the sign of a number.
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index d66e5cb68..602c0ebc5 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1788,8 +1788,10 @@ def amax(a, axis=None, out=None):
 
     Returns
     -------
-    amax : ndarray
-        A new array or scalar array with the result.
+    amax : ndarray or scalar
+        Maximum of `a`. If `axis` is None, the result is a scalar value.
+        If `axis` is given, the result is an array of dimension
+        ``a.ndim - 1``.
 
     See Also
     --------
diff --git a/numpy/doc/structured_arrays.py b/numpy/doc/structured_arrays.py
index a0d84bd79..af777efa4 100644
--- a/numpy/doc/structured_arrays.py
+++ b/numpy/doc/structured_arrays.py
@@ -26,7 +26,7 @@ position we get the second record: ::
 
 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'.
+default names 'f0', 'f1' and 'f2'. ::
 
  >>> y = x['f1']
  >>> y
@@ -118,7 +118,7 @@ like Fortran equivalencing).
 3) List argument: In this case the record structure is defined with a list of
 tuples. Each tuple has 2 or 3 elements specifying: 1) The name of the field
 ('' is permitted), 2) the type of the field, and 3) the shape (optional).
-For example:
+For example::
 
  >>> x = np.zeros(3, dtype=[('x','f4'),('y',np.float32),('value','f4',(2,2))])
  >>> x
@@ -142,7 +142,7 @@ to be strings), where the value of None is permitted. As an example: ::
        dtype=[('col1', '>i4'), ('col2', '>f4')])
 
 The other dictionary form permitted is a dictionary of name keys with tuple
-values specifying type, offset, and an optional title.
+values specifying type, offset, and an optional title. ::
 
  >>> x = np.zeros(3, dtype={'col1':('i1',0,'title 1'), 'col2':('f4',1,'title 2')})
  >>> x
@@ -168,7 +168,7 @@ Accessing field titles
 ====================================
 
 The field titles provide a standard place to put associated info for fields.
-They do not have to be strings.
+They do not have to be strings. ::
 
  >>> x.dtype.fields['x'][2]
  'title 1'
@@ -181,7 +181,7 @@ You can access multiple fields at once using a list of field names: ::
  >>> x = np.array([(1.5,2.5,(1.0,2.0)),(3.,4.,(4.,5.)),(1.,3.,(2.,6.))],
          dtype=[('x','f4'),('y',np.float32),('value','f4',(2,2))])
 
-Notice that `x` is created with a list of tuples.
+Notice that `x` is created with a list of tuples. ::
 
  >>> x[['x','y']]
  array([(1.5, 2.5), (3.0, 4.0), (1.0, 3.0)],
@@ -192,12 +192,28 @@ Notice that `x` is created with a list of tuples.
       dtype=[('x', '<f4'), ('value', '<f4', (2, 2))])
 
 Notice that the fields are always returned in the same order regardless of
-the sequence they are asked for.
+the sequence they are asked for. ::
 
  >>> x[['y','x']]
  array([(1.5, 2.5), (3.0, 4.0), (1.0, 3.0)],
       dtype=[('x', '<f4'), ('y', '<f4')])
 
+Filling structured arrays
+=========================
+
+Structured arrays can be filled by field or row by row. ::
+
+ >>> arr = np.zeros((5,), dtype=[('var1','f8'),('var2','f8')])
+ >>> arr['var1'] = np.arange(5)
+
+If you fill it in row by row, it takes a take a tuple
+(but not a list or array!)::
+
+ >>> arr[0] = (10,20)
+ >>> arr
+ array([(10.0, 20.0), (1.0, 0.0), (2.0, 0.0), (3.0, 0.0), (4.0, 0.0)],
+      dtype=[('var1', '<f8'), ('var2', '<f8')])
+
 More information
 ====================================
 You can find some more information on recarrays and structured  arrays