Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#15 auto undocument for aliases

closed
Edward Loper
Other (25)
5
2008-01-31
2004-04-20
Robin Dunn
No

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__.

Discussion

  • Edward Loper
    Edward Loper
    2004-04-20

    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)

     
  • Robin Dunn
    Robin Dunn
    2004-04-21

    Logged In: YES
    user_id=53955

    Good ideas, thanks.

     
  • Edward Loper
    Edward Loper
    2008-01-31

    • status: open --> closed