[docs] [issue11015] Bring test.support docs up to date

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

This is an improvement that I think should be committed before 3.2.1.
Some comments:

+.. function:: run_doctest(module, verbosity=None)
+   Run :mod:`doctest` on the given *module*.
should be, I believe,
+   Run :func:`doctest.testmod` on the given *module*.
as that is what the function actually does (I check the code).

+   If *verbosity* is :const:`None`, :meth:`doctest` is run with verbosity set
+   to :data:`verbose`.  Otherwise, it is run with verbosity set to
+   :const:`None`.

Should :meth:`doctest` be :func:`testmod` ?
Otherwise the proposed text rewrites

"    If optional argument verbosity is not specified (or is None), pass
    support's belief about verbosity on to doctest.  Else doctest's
    usual behavior is used (it searches sys.argv for -v)."

The problem with the rewrite is that the keyword param of testmod is 'verbose', not 'verbosity'. 'Verbosity' is a dummy name used to either pass support.verbose to verbose, or not. So testmod is, in net effect, run with verbose=verbose or verbose=None. My attempt to explain a bad design (with probable markup errors):

"If *verbosity* is :const:`None`, :func:`testmod` is run with verbose set to :data:`support.verbose`, which is set by :func:`regrtest`. Otherwise, it is run with verbose set to :const:`None` and subsequently replaced by :code:`'-v' in sys.argv`."


+.. function:: temp_umask(umask)
+
+   A context manager that temporarily sets the process umask to the
+   given value.

"sets the process umask to *umask*." ?


+.. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)

+   Either this method or :func:`bind_port` should be used for any tests
+   where a server socket needs to be bound to a particular port for the
+   duration of the test.
+   Which one to use depends on whether the calling code is creating a python
+   socket, or if an unused port needs to be provided in a constructor
+   or passed to an external program (i.e. the ``-accept`` argument to
+   openssl's s_server mode). 

This is copied from the doc string but does really tell me which to use in which of the two situations.

Other additions look OK to me. Some copied docstrings (or comments). Some are new. Support.py could also use a patch to add missing docstings (and turn a couple of comments into docstrings).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11015>
_______________________________________