DOC: add info on docstrings in test functions/methods. Also fix a typo.

doc/TESTS.rst.txt

@@ -116,6 +116,11 @@ Sometimes it is convenient to run ``test_yyy.py`` by itself, so we add
 
 at the bottom.
 
+Note that ``test_`` functions or methods should not have a docstring, because
+that makes it hard to identify the test from the output of running the test
+suite with ``verbose=2`` (or similar verbosity setting).  Use plain comments
+(``#``) if necessary.
+
 Labeling tests with nose
 ------------------------
 
@@ -174,7 +179,7 @@ nose decorators::
 
   @nose.with_setup(setup_func, teardown_func)
   def test_with_extras():
-      """This test uses the setup/teardown functions."""
+      # This test uses the setup/teardown functions.
       global helpful_variable
       print "  In test_with_extras"
       print "  Helpful is %s" % helpful_variable
@@ -205,7 +210,7 @@ hard to see for which parameters.  To avoid this problem, ensure that:
     ``test_*`` generator function, but delegated to a corresponding
     ``check_*`` function (can be inside the generator, to share namespace).
   - The generators are used *solely* for loops over parameters.
-  - These parameters are *not* arrays.
+  - Those parameters are *not* arrays.
 
 .. warning::