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

Brett Cannon brett at python.org
Thu Jun 26 00:27:33 CEST 2008

On Wed, Jun 25, 2008 at 2:00 PM, Guido van Rossum <guido at python.org> wrote:

I'm a little worried about making stuff undocumented that every core developer needs to use -- everyone writing tests needs to continue to use testsupport

Right, but I would think all core developers know about test.support and are capable of reading the code and docstring.

(now test.support?).

In 3.0, yes.

I imagine people writing unit test suites for 3rd party libraries might want to use its services too.

In general I'm not a big fan of having undocumented APIs; 9 out of 10 times someone finds a genuine use case for such an API, and then you're worse off than if it was documented to begin with, since if people start using undocumented APIs, they necessarily reverse-engineer how it works, and then you can never change it. If it was documented, at least you may be able to get away with modifying the undocumented parts, assuming people actually read the docs. (Though we've had cases where the docs and implementation were inconsistent for years, and eventually we ended up fixing the docs...)

My worry is that the module has had stuff tossed in ad-hoc in such a way that maintaining the code for public consumption is a pain. If we took the time to clean up the APIs then I would be fine with documenting the module.

-Brett

More information about the Python-Dev mailing list