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

[Edward D. Loper]

I was looking through the changes made in Python 2.1, and noticed
the "__all__" variable in modules.  My understanding is that, when
defined, this lists all of the variables that will be imported
when you do "from xyz import *".  

Would it also be reasonable for a doc tool to look at this value, for
an indication of which objects to document?  This would be an
easy way of preventing the doc tools from documenting:
  1. "internal" objects (may be a good idea, may not be..)
  2. imported modules and objects that were imported from other 
     modules (most likely a good idea).  (note that this is only
     an issue when we're documenting from within Python, not when
     we're parsing the file that we're documenting.)

(I've had trouble documenting modules that run "from types import *",
and seeing a bunch of Type objects defined by the module, etc..)

Of course, if the __all__ variable is not defined, you'd still have
to use whatever heuristics/rules you have to decide what to document..
And you'd probably want tools to have a flag that tells them to
ignore the __all__ variable.

But mainly I'm wondering whether this is consistant with the intended
meaning of the __all__ variable?  If not, tools shouldn't use it that
way.. we've had enough trouble with people overloading variables
already (pre-function-attribute __doc__ comes to mind).

Also, would it be reasonable to only document the fields of a 
class listed in an __all__ class variable, if such a variable is
defined?

-Edward