Re: [Epydoc-devel] Re: epydoc questions

[Edward L. <ed...@gr...>]

Robin Dunn wrote:
>> But I'm sure you don't want *all* imported objects to be listed as if 
>> they're defined locally.
> 
> Actually, in this case I do want all of them. 

For this one module, maybe, but not in general, right?  So maybe what 
you want is a module-level way of saying "treat imported objects as 
locally defined" instead of an object-level one?

> For the docs my preference would be that "core" and "wx.core" does not 
> show up anywhere, and that everything that lives in wx.core would just 
> be documented as "wx.Whatever".

If "core" isn't listed in wx.__all__, then it will be treated as 
"private."  Combined with treaing all names in __all__ as locally 
defined, this might do what you want.  Alternatively, you might consider 
renaming wx.core to wx._core (which will make it very clear to your 
users that it's an implementation module, and shouldnt be used directly).

>> So epydoc needs some information source to decide which imported 
>> objects  it should pretend are defined locally.
>>
>> One option is to use __all__.  In particular, any imported objects 
>> listed in __all__ will be treated as if they were defined locally.
> 
> With hundreds of objects per module that gets to be a little difficult 
> to maintain...  I'll keep it in mind though.

There's no reason that __all__ has to be defined using a list literal. 
In particular, you might consider doing something like this:

     # Import all objects from wx.core (the implementation module)
     from wx.core import *

     # Declare that all of the objects imported from wx.core are public
     import wx.core
     __all__ += [name for name in dir(wx.core)
                 if not name.startswith('__') and name.endswith('__')]
     del wx.core

>> Another option is to define a new field for the module docstring, that 
>> declares that an object should be treated as if it was defined 
>> locally.  Something like "@local: Window", although I'm not crazy 
>> about that name.
> 
> This too.

@local would presumably support the "*" syntax that's supported by 
@group, @sort, and @undefined.  In particular, you could just do:

     @local: *

I think I like the __all__ solution better, though.

-Edward