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

[Ka-Ping Yee]

> 
> [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.

Tim Peters wrote:
> Well, every time you or I test pydoc under Windows, the first thing we do is
> type "random" at it.

...why, because "random" has those weird bound methods at the top-level
that used to throw pydoc for a loop?  :)

> Because "_" appears early in the alphabet, the first
> four methods it displays are:
> 
> _Random__whseed
> __getstate__
> __init__
> __setstate__

Well, you definitely want to know about __init__.  I can see why you
might not want to see private methods like _Random__whseed, though.
As for __getstate__ and __setstate__, it's probably nice to know that
they exist ("oh, it's possible to pickle this").

> and by ignoring both __all__ *and* the underscore
> conventions, pydoc shows too much irrelevant implementation detail.

I should note that pydoc *did* try both of those things already.
In a previous incarnation, pydoc avoided top-level names beginning
with _, but Guido was unhappy that it did this at the module level
and not at the class level, so i changed it.  In an even earlier
incarnation, pydoc only displayed names listed in __all__, and so
many things were missing from the output that it wasn't useful any
more (e.g. errors in httplib, useful functions in cgi, constants
like keyword.kwlist).  Perhaps if the value of __all__ were
different (or if it's changed in the past couple of weeks) it
would be okay, but at the moment it just hides too much.


-- ?!ng