#15 auto undocument for aliases

Other (25)
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

    Edward Loper - 2004-04-20

    Logged In: YES

    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)

  • Robin Dunn

    Robin Dunn - 2004-04-21

    Logged In: YES

    Good ideas, thanks.

  • Edward Loper

    Edward Loper - 2008-01-31
    • status: open --> closed

Log in to post a comment.