first set of checkins from the doc editor

4 files changed, 86 insertions, 67 deletions

diff --git a/numpy/lib/_datasource.py b/numpy/lib/_datasource.py
index 4bfbf0ac4..957e7cb18 100644
--- a/numpy/lib/_datasource.py
+++ b/numpy/lib/_datasource.py
@@ -176,12 +176,11 @@ class DataSource (object):
 
     Examples
     --------
-
     ::
 
         >>> ds = DataSource('/home/guido')
         >>> urlname = 'http://www.google.com/index.html'
-        >>> gfile = ds.open('http://www.google.com/index.html')  # open remote file
+        >>> gfile = ds.open('http://www.google.com/index.html')  # remote file
         >>> ds.abspath(urlname)
         '/home/guido/www.google.com/site/index.html'
 
diff --git a/numpy/lib/_iotools.py b/numpy/lib/_iotools.py
index c69bd84dc..2c062f1b0 100644
--- a/numpy/lib/_iotools.py
+++ b/numpy/lib/_iotools.py
@@ -391,12 +391,29 @@ def str2bool(value):
 
 
 class ConverterError(Exception):
+    """
+    Exception raised when an error occurs in a converter for string values.
+
+    """
     pass
 
 class ConverterLockError(ConverterError):
+    """
+    Exception raised when an attempt is made to upgrade a locked converter.
+
+    """
     pass
 
 class ConversionWarning(UserWarning):
+    """
+    Warning issued when a string converter has a problem.
+
+    Notes
+    -----
+    In `genfromtxt` a `ConversionWarning` is issued if raising exceptions
+    is explicitly suppressed with the "invalid_raise" keyword.
+
+    """
     pass
 
 
@@ -708,22 +725,23 @@ def easy_dtype(ndtype, names=None, defaultfmt="f%i", **validationargs):
     """
     Convenience function to create a `np.dtype` object.
 
-    The function processes the input dtype and matches it with the given names.
+    The function processes the input `dtype` and matches it with the given
+    names.
 
     Parameters
     ----------
     ndtype : var
-        Definition of the dtype. Can be any string or dictionary recognized
-        by the `np.dtype` function or a sequence of types.
+        Definition of the dtype. Can be any string or dictionary
+        recognized by the `np.dtype` function, or a sequence of types.
     names : str or sequence, optional
         Sequence of strings to use as field names for a structured dtype.
         For convenience, `names` can be a string of a comma-separated list of
-        names
+        names.
     defaultfmt : str, optional
-        Format string used to define missing names, such as "f%i" (default),
-        "fields_%02i"...
+        Format string used to define missing names, such as ``"f%i"``
+        (default) or ``"fields_%02i"``.
     validationargs : optional
-        A series of optional arguments used to initialize a NameValidator.
+        A series of optional arguments used to initialize a `NameValidator`.
 
     Examples
     --------
@@ -733,10 +751,12 @@ def easy_dtype(ndtype, names=None, defaultfmt="f%i", **validationargs):
     dtype([('f0', '<i4'), ('f1', '<f8')])
     >>> np.lib._iotools.easy_dtype("i4, f8", defaultfmt="field_%03i")
     dtype([('field_000', '<i4'), ('field_001', '<f8')])
+
     >>> np.lib._iotools.easy_dtype((int, float, float), names="a,b,c")
     dtype([('a', '<i8'), ('b', '<f8'), ('c', '<f8')])
     >>> np.lib._iotools.easy_dtype(float, names="a,b,c")
     dtype([('a', '<f8'), ('b', '<f8'), ('c', '<f8')])
+
     """
     try:
         ndtype = np.dtype(ndtype)
diff --git a/numpy/lib/scimath.py b/numpy/lib/scimath.py
index a3fe1def7..57cf92aaa 100644
--- a/numpy/lib/scimath.py
+++ b/numpy/lib/scimath.py
@@ -167,48 +167,39 @@ def _fix_real_abs_gt_1(x):
 
 def sqrt(x):
     """
-    Return the square root of x.
+    Compute the square root of x.
+
+    For negative input elements, a complex value is returned
+    (unlike `numpy.sqrt` which returns NaN).
 
     Parameters
     ----------
     x : array_like
+       The input value(s).
 
     Returns
     -------
-    out : array_like
-
-    Notes
-    -----
-
-    As the numpy.sqrt, this returns the principal square root of x, which is
-    what most people mean when they use square root; the principal square root
-    of x is not any number z such as z^2 = x.
-
-    For positive numbers, the principal square root is defined as the positive
-    number z such as z^2 = x.
+    out : ndarray or scalar
+       The square root of `x`. If `x` was a scalar, so is `out`,
+       otherwise an array is returned.
 
-    The principal square root of -1 is i, the principal square root of any
-    negative number -x is defined a i * sqrt(x). For any non zero complex
-    number, it is defined by using the following branch cut: x = r e^(i t) with
-    r > 0 and -pi < t <= pi. The principal square root is then
-    sqrt(r) e^(i t/2).
+    See Also
+    --------
+    numpy.sqrt
 
     Examples
     --------
-
-    For real, non-negative inputs this works just like numpy.sqrt():
+    For real, non-negative inputs this works just like `numpy.sqrt`:
 
     >>> np.lib.scimath.sqrt(1)
     1.0
-
-    >>> np.lib.scimath.sqrt([1,4])
+    >>> np.lib.scimath.sqrt([1, 4])
     array([ 1.,  2.])
 
     But it automatically handles negative inputs:
 
     >>> np.lib.scimath.sqrt(-1)
     (0.0+1.0j)
-
     >>> np.lib.scimath.sqrt([-1,4])
     array([ 0.+1.j,  2.+0.j])
 
@@ -227,14 +218,14 @@ def log(x):
 
     Parameters
     ----------
-    x : array_like or scalar
+    x : array_like
        The value(s) whose log is (are) required.
 
     Returns
     -------
     out : ndarray or scalar
        The log of the `x` value(s). If `x` was a scalar, so is `out`,
-       otherwise an array object is returned.
+       otherwise an array is returned.
 
     See Also
     --------
@@ -252,8 +243,8 @@ def log(x):
     >>> np.emath.log(np.exp(1))
     1.0
 
-    Negative arguments are handled "correctly" (recall that `exp(log(x)) == x`
-    does *not* hold for real `x < 0`):
+    Negative arguments are handled "correctly" (recall that
+    ``exp(log(x)) == x`` does *not* hold for real ``x < 0``):
 
     >>> np.emath.log(-np.exp(1)) == (1 + np.pi * 1j)
     True
@@ -314,28 +305,29 @@ def logn(n, x):
     """
     Take log base n of x.
 
-    If x contains negative inputs, the answer is computed and returned in the
+    If `x` contains negative inputs, the answer is computed and returned in the
     complex domain.
 
     Parameters
     ----------
+    n : int
+       The base in which the log is taken.
     x : array_like
+       The value(s) whose log base `n` is (are) required.
 
     Returns
     -------
-    out : array_like
+    out : ndarray or scalar
+       The log base `n` of the `x` value(s). If `x` was a scalar, so is
+       `out`, otherwise an array is returned.
 
     Examples
     --------
-
-    (We set the printing precision so the example can be auto-tested)
-
     >>> np.set_printoptions(precision=4)
 
-    >>> np.lib.scimath.logn(2,[4,8])
+    >>> np.lib.scimath.logn(2, [4, 8])
     array([ 2.,  3.])
-
-    >>> np.lib.scimath.logn(2,[-4,-8,8])
+    >>> np.lib.scimath.logn(2, [-4, -8, 8])
     array([ 2.+4.5324j,  3.+4.5324j,  3.+0.j    ])
 
     """
@@ -354,14 +346,14 @@ def log2(x):
 
     Parameters
     ----------
-    x : array_like or scalar
+    x : array_like
        The value(s) whose log base 2 is (are) required.
 
     Returns
     -------
     out : ndarray or scalar
        The log base 2 of the `x` value(s). If `x` was a scalar, so is `out`,
-       otherwise an array object is returned.
+       otherwise an array is returned.
 
     See Also
     --------
@@ -376,14 +368,12 @@ def log2(x):
 
     Examples
     --------
-
-    (We set the printing precision so the example can be auto-tested)
+    We set the printing precision so the example can be auto-tested:
 
     >>> np.set_printoptions(precision=4)
 
     >>> np.emath.log2(8)
     3.0
-
     >>> np.emath.log2([-4, -8, 8])
     array([ 2.+4.5324j,  3.+4.5324j,  3.+0.j    ])
 
@@ -393,34 +383,40 @@ def log2(x):
 
 def power(x, p):
     """
-    Return x**p.
-
-    If x contains negative values, it is converted to the complex domain.
+    Return x to the power p, (x**p).
 
-    If p contains negative values, it is converted to floating point.
+    If `x` contains negative values, the output is converted to the
+    complex domain.
 
     Parameters
     ----------
     x : array_like
-    p : array_like of integers
+        The input value(s).
+    p : array_like of ints
+        The power(s) to which `x` is raised. If `x` contains multiple values,
+        `p` has to either be a scalar, or contain the same number of values
+        as `x`. In the latter case, the result is
+        ``x[0]**p[0], x[1]**p[1], ...``.
 
     Returns
     -------
-    out : array_like
+    out : ndarray or scalar
+        The result of ``x**p``. If `x` and `p` are scalars, so is `out`,
+        otherwise an array is returned.
 
-    Examples
+    See Also
     --------
-    (We set the printing precision so the example can be auto-tested)
+    numpy.power
 
+    Examples
+    --------
     >>> np.set_printoptions(precision=4)
 
-    >>> np.lib.scimath.power([2,4],2)
+    >>> np.lib.scimath.power([2, 4], 2)
     array([ 4, 16])
-
-    >>> np.lib.scimath.power([2,4],-2)
+    >>> np.lib.scimath.power([2, 4], -2)
     array([ 0.25  ,  0.0625])
-
-    >>> np.lib.scimath.power([-2,4],2)
+    >>> np.lib.scimath.power([-2, 4], 2)
     array([  4.+0.j,  16.+0.j])
 
     """
@@ -527,14 +523,14 @@ def arctanh(x):
 
     Parameters
     ----------
-    x : array_like or scalar
+    x : array_like
        The value(s) whose arctanh is (are) required.
 
     Returns
     -------
     out : ndarray or scalar
        The inverse hyperbolic tangent(s) of the `x` value(s). If `x` was
-       a scalar so is `out`, otherwise an array object is returned.
+       a scalar so is `out`, otherwise an array is returned.
 
 
     See Also
@@ -551,10 +547,9 @@ def arctanh(x):
     --------
     >>> np.set_printoptions(precision=4)
 
-    >>> np.emath.arctanh(np.matrix(np.eye(2))) # Note: an array is returned
+    >>> np.emath.arctanh(np.matrix(np.eye(2)))
     array([[ Inf,   0.],
            [  0.,  Inf]])
-
     >>> np.emath.arctanh([1j])
     array([ 0.+0.7854j])
 
diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py
index e030abf4f..43d6ede1f 100644
--- a/numpy/lib/utils.py
+++ b/numpy/lib/utils.py
@@ -96,9 +96,14 @@ else:
         return func
 
 class _Deprecate(object):
-    """Decorator class to deprecate old functions.
+    """
+    Decorator class to deprecate old functions.
+
+    Refer to `deprecate` for details.
 
-    Refer to ``decorate``.
+    See Also
+    --------
+    deprecate
 
     """
     def __init__(self, old_name=None, new_name=None, message=None):