updated docstrings from pydoc website (thanks to everyone who contributed!)

5 files changed, 115 insertions, 41 deletions

diff --git a/numpy/core/defchararray.py b/numpy/core/defchararray.py
index 4530bd5ad..27bcb352b 100644
--- a/numpy/core/defchararray.py
+++ b/numpy/core/defchararray.py
@@ -4,12 +4,12 @@ operations and methods.
 
 .. note::
    The `chararray` class exists for backwards compatibility with
-   Numarray, it is not recommended for new development. If one needs
-   arrays of strings, use arrays of `dtype` `object_`, `string_` or
-   `unicode_`, and use the free functions in the `numpy.char` module
-   for fast vectorized string operations.
+   Numarray, it is not recommended for new development. Starting from numpy
+   1.4, if one needs arrays of strings, it is recommended to use arrays of
+   `dtype` `object_`, `string_` or `unicode_`, and use the free functions
+   in the `numpy.char` module for fast vectorized string operations.
 
-Some methods will only be available if the corresponding str method is
+Some methods will only be available if the corresponding string method is
 available in your version of Python.
 
 The preferred alias for `defchararray` is `numpy.char`.
@@ -1692,10 +1692,10 @@ class chararray(ndarray):
 
     .. note::
        The `chararray` class exists for backwards compatibility with
-       Numarray, it is not recommended for new development. If one needs
-       arrays of strings, use arrays of `dtype` `object_`, `string_` or
-       `unicode_`, and use the free functions in the `numpy.char` module
-       for fast vectorized string operations.
+       Numarray, it is not recommended for new development. Starting from numpy
+       1.4, if one needs arrays of strings, it is recommended to use arrays of
+       `dtype` `object_`, `string_` or `unicode_`, and use the free functions
+       in the `numpy.char` module for fast vectorized string operations.
 
     Versus a regular Numpy array of type `str` or `unicode`, this
     class adds the following functionality:
@@ -1718,6 +1718,71 @@ class chararray(ndarray):
     ``len(shape) >= 2`` and ``order='Fortran'``, in which case `strides`
     is in "Fortran order".
 
+    Methods
+    -------
+    astype
+    argsort
+    copy
+    count
+    decode
+    dump
+    dumps
+    encode
+    endswith
+    expandtabs
+    fill
+    find
+    flatten
+    getfield
+    index
+    isalnum
+    isalpha
+    isdecimal
+    isdigit
+    islower
+    isnumeric
+    isspace
+    istitle
+    isupper
+    item
+    join
+    ljust
+    lower
+    lstrip
+    nonzero
+    put
+    ravel
+    repeat
+    replace
+    reshape
+    resize
+    rfind
+    rindex
+    rjust
+    rsplit
+    rstrip
+    searchsorted
+    setfield
+    setflags
+    sort
+    split
+    splitlines
+    squeeze
+    startswith
+    strip
+    swapaxes
+    swapcase
+    take
+    title
+    tofile
+    tolist
+    tostring
+    translate
+    transpose
+    upper
+    view
+    zfill
+
     Parameters
     ----------
     shape : tuple
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index b9265216f..b255e89af 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -127,10 +127,28 @@ def reshape(a, newshape, order='C'):
         This will be a new view object if possible; otherwise, it will
         be a copy.
 
+
     See Also
     --------
     ndarray.reshape : Equivalent method.
 
+    Notes
+    -----
+
+    It is not always possible to change the shape of an array without
+    copying the data. If you want an error to be raise if the data is copied,
+    you should assign the new shape to the shape attribute of the array::
+
+     >>> a = np.zeros((10, 2))
+     # A transpose make the array non-contiguous
+     >>> b = a.T
+     # Taking a view makes it possible to modify the shape without modiying the
+     # initial object.
+     >>> c = b.view()
+     >>> c.shape = (20)
+     AttributeError: incompatible shape for a non-contiguous array
+
+
     Examples
     --------
     >>> a = np.array([[1,2,3], [4,5,6]])
@@ -1708,7 +1726,7 @@ def ptp(a, axis=None, out=None):
 
 def amax(a, axis=None, out=None):
     """
-    Return the maximum along an axis.
+    Return the maximum of an array or maximum along an axis.
 
     Parameters
     ----------
@@ -1724,8 +1742,7 @@ def amax(a, axis=None, out=None):
     Returns
     -------
     amax : ndarray
-        A new array or a scalar with the result, or a reference to `out`
-        if it was specified.
+        A new array or a scalar array with the result.
 
     See Also
     --------
@@ -1769,7 +1786,7 @@ def amax(a, axis=None, out=None):
 
 def amin(a, axis=None, out=None):
     """
-    Return the minimum along an axis.
+    Return the minimum of an array or minimum along an axis.
 
     Parameters
     ----------
@@ -1785,8 +1802,7 @@ def amin(a, axis=None, out=None):
     Returns
     -------
     amin : ndarray
-        A new array or a scalar with the result, or a reference to `out` if it
-        was specified.
+        A new array or a scalar array with the result.
 
     See Also
     --------
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 176212d09..fba6512b2 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -262,6 +262,14 @@ def asarray(a, dtype=None, order=None):
     >>> np.asarray(a) is a
     True
 
+    If `dtype` is set, array is copied only if dtype does not match:
+
+    >>> a = np.array([1, 2], dtype=np.float32)
+    >>> np.asarray(a, dtype=np.float32) is a
+    True
+    >>> np.asarray(a, dtype=np.float64) is a
+    False
+
     Contrary to `asanyarray`, ndarray subclasses are not passed through:
 
     >>> issubclass(np.matrix, np.ndarray)
@@ -2090,25 +2098,6 @@ def seterr(all=None, divide=None, over=None, under=None, invalid=None):
     Warning: overflow encountered in short_scalars
     30464
 
-    Calling `seterr` with no arguments resets treatment for all floating-point
-    errors to the defaults. XXX: lies!!! code doesn't do that
-    >>> np.geterr()
-    {'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore', 'under': 'ignore'}
-    >>> np.seterr(all='warn')
-    {'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore', 'under': 'ignore'}
-    >>> np.geterr()
-    {'over': 'warn', 'divide': 'warn', 'invalid': 'warn', 'under': 'warn'}
-    >>> np.seterr() # XXX: this should reset to defaults according to docstring above
-    {'over': 'warn', 'divide': 'warn', 'invalid': 'warn', 'under': 'warn'}
-    >>> np.geterr() # XXX: but clearly it doesn't
-    {'over': 'warn', 'divide': 'warn', 'invalid': 'warn', 'under': 'warn'}
-
-    >>> old_settings = np.seterr()
-    >>> old_settings = np.seterr(all='ignore')
-    >>> np.geterr()
-    {'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore',
-    'under': 'ignore'}
-
     """
 
     pyvals = umath.geterrobj()
diff --git a/numpy/core/numerictypes.py b/numpy/core/numerictypes.py
index f9938761d..f47e05391 100644
--- a/numpy/core/numerictypes.py
+++ b/numpy/core/numerictypes.py
@@ -1,6 +1,7 @@
-"""numerictypes: Define the numeric type objects
+"""
+numerictypes: Define the numeric type objects
 
-This module is designed so 'from numerictypes import *' is safe.
+This module is designed so "from numerictypes import \\*" is safe.
 Exported symbols include:
 
   Dictionary with all registered number types (including aliases):
@@ -37,8 +38,10 @@ Exported symbols include:
     float_, complex_,
     longfloat, clongfloat,
 
-    datetime_, timedelta_,  (these inherit from timeinteger which inherits from signedinteger)
-    
+
+    datetime_, timedelta_,  (these inherit from timeinteger which inherits
+    from signedinteger)
+
 
    As part of the type-hierarchy:    xx -- is bit-width
 
@@ -65,7 +68,7 @@ Exported symbols include:
      |   |     single
      |   |     float_  (double)
      |   |     longfloat
-     |   \-> complexfloating    (complexxx)     (kind=c)
+     |   \\-> complexfloating    (complexxx)     (kind=c)
      |         csingle  (singlecomplex)
      |         complex_ (cfloat, cdouble)
      |         clongfloat (longcomplex)
@@ -75,7 +78,8 @@ Exported symbols include:
      |     unicode_                             (kind=U)
      |     void                                 (kind=V)
      |
-     \-> object_ (not used much)                (kind=O)
+     \\-> object_ (not used much)                (kind=O)
+
 """
 
 # we add more at the bottom
diff --git a/numpy/core/shape_base.py b/numpy/core/shape_base.py
index d3a2953ed..c86684c6f 100644
--- a/numpy/core/shape_base.py
+++ b/numpy/core/shape_base.py
@@ -218,7 +218,7 @@ def hstack(tup):
     Stack arrays in sequence horizontally (column wise).
 
     Take a sequence of arrays and stack them horizontally to make
-    a single array. Rebuild arrays divided by ``hsplit``.
+    a single array. Rebuild arrays divided by `hsplit`.
 
     Parameters
     ----------