[Doc-SIG] __all__, and how it relates to doc tools

[Tim Peters]

[Edward]
> Would it also be reasonable for a doc tool to look at this value, for
> an indication of which objects to document?

[Tim]
> Absolutely.  In fact, that's probably the best use.

[Guido]
> Hm.  You may be right, but Ping told me that he had tried this in
> pyoc, and was unhapy with the result: too much stuff didn't get
> documented.  So we should at least be willing to retract this idea.

Well, every time you or I test pydoc under Windows, the first thing we do is
type "random" at it.  Because "_" appears early in the alphabet, the first
four methods it displays are:

_Random__whseed
__getstate__
__init__
__setstate__

The first 8 functions:

_acos
_cos
_exp
_log
_sin
_sqrt
_test
_test_generator

and then vrbls like _e, _inst and _pi.  Almost none of that is of any
interest to end users, while random.__all__ lists exactly what *is*
interesting to users.  However, random.__all__ is redundant, because
random.py uses the underscore *convention* with care, and __all__ merely
contains the names "import *" would import if __all__ didn't exist.

Some old modules are much sloppier in their use of underscores, and Skip put
a lot of work (when adding __all__ to them) into figuring out which names
they *did* intend to export.  pydoc can't do a better job of guessing *that*
than Skip did by hand, and by ignoring both __all__ *and* the underscore
conventions, pydoc shows too much irrelevant implementation detail.

You eventually need an option to show "private" stuff too, but that's a poor
default choice except for people working on a module's implementation.  I'm
happy to live with the underscore conventions alone to make the
public-private distinction, but since history shows that few others are
willing to live with that, something like __all__ does serve a purpose and
should be respected.