[Python-Dev] Undocumenting test.support in 3.x (was Py3k DeprecationWarning in stdlib)

[Simon Cross]

On Thu, Jun 26, 2008 at 12:27 AM, Brett Cannon <brett at python.org> wrote:
> Right, but I would think all core developers know about test.support
> and are capable of reading the code and docstring.

Docstrings don't help for things other than Modules, Classes and
Functions.  So, for example, are constants like FUZZ intended to be
part of the external API provided by the module or not? Also, there
are already a fair number of functions in test_support that don't have
docstrings. Are these intended to be part of the API?

Obviously one can grep around the existing tests to see what they do,
but then one ends up perpetuating any errors others have made.

While one could possibly attempt to make a case for "all core
developers know" [1] it certainly isn't true that "all future core
developers know" [2] or that "all people who could put patches into
the issue tracker know" [3].

[1] Although personally I would bet against it until proven --
especially given a sensible definition of "core developer" to mean, in
this case, anyone with the right to commit tests to the repository.
[2] Since many of these future developers probably don't even use Python yet.
[3] And we do want patches to issues to include tests, right?