#8 @param *args and **kw: doesn't work.

epytext (18)

Twisted has some methods that use *args and **kw, e.g.:

interaction(self, interaction, callback, errback,
*args, **kw)

(from twisted.enterprise.adbapi.ConnectionPool).

I'd like to be able to document the *args and *kw
together in an @param, e.g. like this:

@param *args,**kw: additional arguments to be
passed to 'interaction'

However epydoc currently decides this is a mal-formed
field, and renders the docstring in plaintext.

I don't want to have seperate "@param *args:" and
"@param **kw:", because they aren't seperate. They
used together, and the idiom of a function accepting
extra arguments in *args and **kw is quite common in
parts of Twisted, so it would be nice if it was
supported by epydoc, which otherwise does an excellent job.



  • Nobody/Anonymous

    Logged In: NO

    I just ran in to this issue also. However, I think I would like
    to be able to do something like this:

    def foo(bar, **kwargs):
    """The foo function.

    @param bar: Base bar value.
    @param bar2: End bar value.
    @param baz: Detect bar value automatically.

    In other words, be able to have param entries for parameters
    that are not specifically mentioned in the parameter list.

  • Edward Loper

    Edward Loper - 2003-07-17

    Logged In: YES

    I just added a "@keyword" (aka "@kwarg") field to the cvs
    version, which should address the follow-up question that
    asked about providing descriptions for individual keyword
    arguments. But I'm still trying to hash out exactly how to
    do the "@param *args and *kw*" thing. It will most likely
    look like:

    @param args, kw: ...

    (note: no *'s, and comma-delimited) You would be
    allowed to use it for any combination of parameters. E.g.:

    >>> def f(a,b,c,d):
    ... """
    ... @param a,b,d: The cool parameters.
    ... """

  • Andrew Bennetts

    Andrew Bennetts - 2003-07-18

    Logged In: YES

    Yeah, I think being able to combine descriptions like:
    @param args, kw: ...
    is the main thing, now that I think about it -- the "*" and
    "**" should be visible in the function prototype anyway.

  • Edward Loper

    Edward Loper - 2003-07-21
    • status: open --> closed
  • Edward Loper

    Edward Loper - 2003-07-21
    • status: closed --> closed-accepted
  • Edward Loper

    Edward Loper - 2003-07-21

    Logged In: YES

    This is now supported (in the cvs version), with the
    following syntax:

    @param *args, **kw: ...

    This syntax can be used to group the descriptions of any
    list of parameters into a single description. In the output
    documentation, the parameters will be listed together,
    with a single description. The params in the list will be
    listed in the order that they appear in the signature, and
    the whole list will be displayed in the position where the
    first param would normally be displayed. Currently, types
    are not displayed correctly for joined param fields, but
    they will be shortly.


Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks