#15 auto undocument for aliases

[Robin Dunn]

In wxPython I sometimes use method aliases to help with
backwards compatibility. For example, the wx.Sizer
class has an Add method, and also a line "AddWindow =
AddSizer = AddSpacer = Add". Currently epydoc is
documenting AddWindow, AddSizer, and AddSpacer, but it
would be nice if it could automatically @undocument
classes. funcitons, methods, etc. where the name
doesn't match the object's real __name__.

[Edward Loper]

Logged In: YES
user_id=195958

But sometimes people *do* want the aliased methods to
be listed. Epydoc doesn't have any way to guess whether
you want an alias to be listed or not, unless you tell it. So
we have to require the user to either explicitly tell us that
an alias *should* be displayed or explicitly tell us that it
should *not* be displayed. I chose the latter.

Another option might be to define a decorator
called "depricated" that issues a DepricationWarning when
the function is called. (This could also be used with the
new decorator syntax that's been proposed for Python
2.4.) Epydoc could then be made aware of this decorator,
and either not display depricated objects, or mark them
explicitly as depricated (based on a command-line option,
probably). Under this scenario, you would replace your
current direct assignment with:

AddWindow = depricated(Add)
AddSpacer = depricated(Add)
AddSizer = depricated(Add)

[Edward Loper]

Logged In: YES
user_id=195958

For more on the "deprecated" decorator, see GVR's email:

http://mail.python.org/pipermail/python-dev/2004-
April/043957.html

[Robin Dunn]

Logged In: YES
user_id=53955

Good ideas, thanks.