Docstring update: testing

1 files changed, 138 insertions, 67 deletions

diff --git a/numpy/testing/decorators.py b/numpy/testing/decorators.py
index e337c35e2..afb52d3ea 100644
--- a/numpy/testing/decorators.py
+++ b/numpy/testing/decorators.py
@@ -1,79 +1,117 @@
-"""Decorators for labeling test objects
+"""
+Decorators for labeling and modifying behavior of test objects.
 
 Decorators that merely return a modified version of the original
-function object are straightforward.  Decorators that return a new
+function object are straightforward. Decorators that return a new
 function object need to use
-nose.tools.make_decorator(original_function)(decorator) in returning
-the decorator, in order to preserve metadata such as function name,
-setup and teardown functions and so on - see nose.tools for more
-information.
+::
+
+  nose.tools.make_decorator(original_function)(decorator)
+
+in returning the decorator, in order to preserve meta-data such as
+function name, setup and teardown functions and so on - see
+``nose.tools`` for more information.
 
 """
 import warnings
 import sys
 
 def slow(t):
-    """Labels a test as 'slow'.
+    """
+    Label a test as 'slow'.
 
     The exact definition of a slow test is obviously both subjective and
     hardware-dependent, but in general any individual test that requires more
     than a second or two should be labeled as slow (the whole suite consits of
-    thousands of tests, so even a second is significant)."""
+    thousands of tests, so even a second is significant).
+
+    Parameters
+    ----------
+    t : callable
+        The test to label as slow.
+
+    Returns
+    -------
+    t : callable
+        The decorated test `t`.
+
+    Examples
+    --------
+    The `numpy.testing` module includes ``import decorators as dec``.
+    A test can be decorated as slow like this::
+
+      from numpy.testing import *
+
+      @dec.slow
+      def test_big(self):
+          print 'Big, slow test'
+
+    """
 
     t.slow = True
     return t
 
 def setastest(tf=True):
-    ''' Signals to nose that this function is or is not a test
+    """
+    Signals to nose that this function is or is not a test.
 
     Parameters
     ----------
     tf : bool
-        If True specifies this is a test, not a test otherwise
+        If True, specifies that the decorated callable is a test.
+        If False, specifies that the decorated callable is not a test.
+        Default is True.
+
+    Notes
+    -----
+    This decorator can't use the nose namespace, because it can be
+    called from a non-test module. See also ``istest`` and ``nottest`` in
+    ``nose.tools``.
 
-    e.g
-    >>> from numpy.testing.decorators import setastest
-    >>> @setastest(False)
-    ... def func_with_test_in_name(arg1, arg2): pass
-    ...
-    >>>
+    Examples
+    --------
+    `setastest` can be used in the following way::
 
-    This decorator cannot use the nose namespace, because it can be
-    called from a non-test module. See also istest and nottest in
-    nose.tools
+      from numpy.testing.decorators import setastest
 
-    '''
+      @setastest(False)
+      def func_with_test_in_name(arg1, arg2):
+          pass
+
+    """
     def set_test(t):
         t.__test__ = tf
         return t
     return set_test
 
 def skipif(skip_condition, msg=None):
-    ''' Make function raise SkipTest exception if skip_condition is true
+    """
+    Make function raise SkipTest exception if a given condition is true.
+
+    If the condition is a callable, it is used at runtime to dynamically
+    make the decision. This is useful for tests that may require costly
+    imports, to delay the cost until the test suite is actually executed.
 
     Parameters
     ----------
-    skip_condition : bool or callable.
-        Flag to determine whether to skip test.  If the condition is a
-        callable, it is used at runtime to dynamically make the decision.  This
-        is useful for tests that may require costly imports, to delay the cost
-        until the test suite is actually executed.
-    msg : string
-        Message to give on raising a SkipTest exception
-
-   Returns
-   -------
-   decorator : function
-       Decorator, which, when applied to a function, causes SkipTest
-       to be raised when the skip_condition was True, and the function
-       to be called normally otherwise.
+    skip_condition : bool or callable
+        Flag to determine whether to skip the decorated test.
+    msg : str, optional
+        Message to give on raising a SkipTest exception. Default is None.
+
+    Returns
+    -------
+    decorator : function
+        Decorator which, when applied to a function, causes SkipTest
+        to be raised when `skip_condition` is True, and the function
+        to be called normally otherwise.
 
     Notes
     -----
-    You will see from the code that we had to further decorate the
-    decorator with the nose.tools.make_decorator function in order to
-    transmit function name, and various other metadata.
-    '''
+    The decorator itself is decorated with the ``nose.tools.make_decorator``
+    function in order to transmit function name, and various other metadata.
+
+    """
 
     def skip_decorator(f):
         # Local import to avoid a hard nose dependency and only incur the
@@ -124,32 +162,35 @@ def skipif(skip_condition, msg=None):
 
 
 def knownfailureif(fail_condition, msg=None):
-    ''' Make function raise KnownFailureTest exception if fail_condition is true
+    """
+    Make function raise KnownFailureTest exception if given condition is true.
+
+    If the condition is a callable, it is used at runtime to dynamically
+    make the decision. This is useful for tests that may require costly
+    imports, to delay the cost until the test suite is actually executed.
 
     Parameters
     ----------
-    fail_condition : bool or callable.
-        Flag to determine whether to mark test as known failure (True)
-        or not (False).  If the condition is a callable, it is used at
-        runtime to dynamically make the decision.  This is useful for 
-        tests that may require costly imports, to delay the cost
-        until the test suite is actually executed.
-    msg : string
-        Message to give on raising a KnownFailureTest exception
-
-   Returns
-   -------
-   decorator : function
-       Decorator, which, when applied to a function, causes SkipTest
-       to be raised when the skip_condition was True, and the function
-       to be called normally otherwise.
+    fail_condition : bool or callable
+        Flag to determine whether to mark the decorated test as a known
+        failure (if True) or not (if False).
+    msg : str, optional
+        Message to give on raising a KnownFailureTest exception.
+        Default is None.
+
+    Returns
+    -------
+    decorator : function
+        Decorator, which, when applied to a function, causes SkipTest
+        to be raised when `skip_condition` is True, and the function
+        to be called normally otherwise.
 
     Notes
     -----
-    You will see from the code that we had to further decorate the
-    decorator with the nose.tools.make_decorator function in order to
-    transmit function name, and various other metadata.
-    '''
+    The decorator itself is decorated with the ``nose.tools.make_decorator``
+    function in order to transmit function name, and various other metadata.
+
+    """
     if msg is None:
         msg = 'Test skipped due to known failure'
 
@@ -177,7 +218,15 @@ def knownfailureif(fail_condition, msg=None):
 # manager)
 class WarningMessage(object):
 
-    """Holds the result of a single showwarning() call."""
+    """
+    Holds the result of a single showwarning() call.
+
+    Notes
+    -----
+    `WarningMessage` is copied from the Python 2.6 warnings module,
+    so it can be used in NumPy with older Python versions.
+
+    """
 
     _WARNING_DETAILS = ("message", "category", "filename", "lineno", "file",
                         "line")
@@ -198,6 +247,27 @@ class WarningMessage(object):
                                     self.filename, self.lineno, self.line))
 
 class WarningManager:
+    """
+    A context manager that copies and restores the warnings filter upon
+    exiting the context.
+
+    The 'record' argument specifies whether warnings should be captured by a
+    custom implementation of ``warnings.showwarning()`` and be appended to a
+    list returned by the context manager. Otherwise None is returned by the
+    context manager. The objects appended to the list are arguments whose
+    attributes mirror the arguments to ``showwarning()``.
+
+    The 'module' argument is to specify an alternative module to the module
+    named 'warnings' and imported under that name. This argument is only useful
+    when testing the warnings module itself.
+
+    Notes
+    -----
+    `WarningManager` is a copy of the ``catch_warnings`` context manager
+    from the Python 2.6 warnings module, with slight modifications.
+    It is copied so it can be used in NumPy with older Python versions.
+
+    """
     def __init__(self, record=False, module=None):
         self._record = record
         if module is None:
@@ -229,28 +299,29 @@ class WarningManager:
         self._module.showwarning = self._showwarning
 
 def deprecated(conditional=True):
-    """This decorator can be used to filter Deprecation Warning, to avoid
+    """
+    Filter deprecation warnings while running the test suite.
+
+    This decorator can be used to filter DeprecationWarning's, to avoid
     printing them during the test suite run, while checking that the test
     actually raises a DeprecationWarning.
 
     Parameters
     ----------
-    conditional : bool or callable.
+    conditional : bool or callable, optional
         Flag to determine whether to mark test as deprecated or not. If the
         condition is a callable, it is used at runtime to dynamically make the
-        decision.
+        decision. Default is True.
 
     Returns
     -------
     decorator : function
-        Decorator, which, when applied to a function, causes SkipTest
-        to be raised when the skip_condition was True, and the function
-        to be called normally otherwise.
+        The `deprecated` decorator itself.
 
     Notes
     -----
-
     .. versionadded:: 1.4.0
+
     """
     def deprecate_decorator(f):
         # Local import to avoid a hard nose dependency and only incur the