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

[Brett Cannon]

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 test_support

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