#32 Recognize conventions for public functions with --parse-only

[Noam Yorav-Raphael]

Hello,

I am now using epydoc to document Python modules where
I work, and I have decided to use the --parse-only
option, as actually importing the modules sometimes
causes trouble.

For some modules, we are using a different convention
for declaring public members of a module. Instead of
writing at the beginning of the module:

__all__ = ['func1', 'func2', ...]

we are writing at the beginning:

__all__ = []

and before each function or class add its name to the
list. For example:

__all__.append('foo')
def foo():
print 'Walla!'

Using this way, it's easier to manage the __all__ list
- otherwise, it's easy to forget about adding and
removing names from the __all__ list.

Another convention, which can be used as of Python 2.3,
is using decorators. You define at the beginning of the
module something like this:

__all__ = []

def public(func):
__all__.append(func.func_name)
return func

Then, you can declare public functions like this:

@public
def foo():
print 'Ya habibi!'

Introspection solves all this. However, as I said,
sometimes you don't want to use it. Perhaps it may be
possible to recognize these two conventions/idioms by
parsing only? I mean exactly these:
"__all__.append(name)", and "@public def name" (I don't
think it's needed to recognize what exactly "public"
does - I think the name is enough.)

It may seem too specific, but I don't think of any
other reasonable way to declare a member of a module as
public near its definition.

Thanks,
Noam

[Edward Loper]

Logged In: YES
user_id=195958

I probably won't have time to work on this in the near
future, but the right approach for implementing it would
probably be:

Add a couple clauses do epydoc.docparser.process_line(),
checking for the relevant patterns (i.e., "__all__.append
(<string>)" and "@public"), and delegating to a new
append_to_all() function, which would look up the __all__
variable, and modify its value's toktree (& its
parse_repr?).

If anyone feels up to working on this, I'd be happy to
review patches.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

Added support for:
>>> __all__.append('name')
>>> __all__ += ['name']
>>> @public

in svn revision 1703