On Thu, Jun 26, 2008 at 12:27 AM, Brett Cannon 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?