On Wed, Jun 25, 2008 at 2:00 PM, Guido van Rossum <[EMAIL PROTECTED]> 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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
