Add docstrings to numeric.py, especially for seterr and geterr.

1 files changed, 59 insertions, 7 deletions

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 014a729ff..ce1a87da4 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -69,6 +69,8 @@ def empty_like(a):
 # end Fernando's utilities
 
 def fromiter(obj, dtype=None):
+    """Return an array object from an iterator.
+    """
     obj = list(obj)
     return array(obj, dtype=dtype)
 
@@ -113,24 +115,31 @@ lexsort = multiarray.lexsort
 
 
 def asarray(a, dtype=None, order=None):
-    """returns a as an array.  Unlike array(),
-    no copy is performed if a is already an array.  Subclasses are converted
-    to base class ndarray.
+    """Returns a as an array.
+
+    Unlike array(), no copy is performed if a is already an array. Subclasses
+    are converted to base class ndarray.
     """
     return array(a, dtype, copy=False, order=order)
 
 def asanyarray(a, dtype=None, order=None):
-    """will pass subclasses through...
+    """Returns a as an array, but will pass subclasses through.
     """
     return array(a, dtype, copy=False, order=order, subok=1)
 
 def ascontiguousarray(a, dtype=None):
+    """Return 'a' as an array contiguous in memory (C order).
+    """
     return array(a, dtype, copy=False, order='C', ndmin=1)
 
 def asfortranarray(a, dtype=None):
+    """Return 'a' as an array laid out in Fortran-order in memory.
+    """
     return array(a, dtype, copy=False, order='F', ndmin=1)
 
 def isfortran(a):
+    """Returns True if 'a' is laid out in Fortran-order in memory.
+    """
     return a.flags.fnc
 
 def argwhere(a):
@@ -139,7 +148,7 @@ def argwhere(a):
     converted to a tuple in order to be used to index into a.
     """
     return transpose(a.nonzero())
-    
+
 _mode_from_name_dict = {'v': 0,
                         's' : 1,
                         'f' : 2}
@@ -312,6 +321,8 @@ def fromfunction(function, dimensions, **kwargs):
     return function(*args,**kwargs)
 
 def isscalar(num):
+    """Returns True if the type of num is a scalar type.
+    """
     if isinstance(num, generic):
         return True
     else:
@@ -366,6 +377,9 @@ _cload = load
 _file = file
 
 def load(file):
+    """Wrapper around cPickle.load which accepts either a file-like object or
+    a filename.
+    """
     if isinstance(file, type("")):
         file = _file(file,"rb")
     return _cload(file)
@@ -418,6 +432,23 @@ for key in _errdict.keys():
 del key
 
 def seterr(divide=None, over=None, under=None, invalid=None):
+    """Set how floating-point errors are handled.
+
+    Valid values for each type of error are the strings
+    "ignore", "warn", "raise", and "call". Returns the old settings.
+
+    Note that operations on integer scalar types (such as int16) are
+    handled like floating point, and are affected by these settings.
+
+    Example:
+
+    >>> seterr(over='raise')
+    {'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore', 'under': 'ignore'}
+    >>> int16(32000) * int16(3)
+    Traceback (most recent call last):
+          File "<stdin>", line 1, in ?
+    FloatingPointError: overflow encountered in short_scalars
+    """
 
     pyvals = umath.geterrobj()
     old = geterr()
@@ -437,6 +468,12 @@ def seterr(divide=None, over=None, under=None, invalid=None):
     return old
 
 def geterr():
+    """Get the current way of handling floating-point errors.
+
+    Returns a dictionary with entries "divide", "over", "under", and
+    "invalid", whose values are from the strings
+    "ignore", "warn", "raise", and "call".
+    """
     maskvalue = umath.geterrobj()[1]
     mask = 3
     res = {}
@@ -451,11 +488,13 @@ def geterr():
     return res
 
 def setbufsize(size):
+    """Set the size of the buffer used in ufuncs.
+    """
     if size > 10e6:
         raise ValueError, "Buffer size too big... %s" % size
     if size < 5:
-	raise ValueError, "Buffer size too small... %s" %size
- 
+        raise ValueError, "Buffer size too small... %s" %size
+
     pyvals = umath.geterrobj()
     old = getbufsize()
     pyvals[0] = size
@@ -463,9 +502,20 @@ def setbufsize(size):
     return old
 
 def getbufsize():
+    """Return the size of the buffer used in ufuncs.
+    """
     return umath.geterrobj()[0]
 
 def seterrcall(func):
+    """Set the callback function used when a floating-point error handler
+    is set to 'call'.
+
+    'func' should be a function that takes two arguments. The first is
+    type of error ("divide", "over", "under", or "invalid"), and the second
+    is the status flag (= divide + 2*over + 4*under + 8*invalid).
+
+    Returns the old handler.
+    """
     if func is not None and not callable(func):
         raise ValueError, "Only callable can be used as callback"
     pyvals = umath.geterrobj()
@@ -475,6 +525,8 @@ def seterrcall(func):
     return old
 
 def geterrcall():
+    """Return the current callback function used on floating-point errors.
+    """
     return umath.geterrobj()[2]
 
 def _setdef():