Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

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

v1.1
closed-accepted
Edward Loper
epytext (18)
5
2003-07-21
2002-11-16
Andrew Bennetts
No

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.

Thanks.

Discussion

  • 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
    user_id=195958

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

     
  • Logged In: YES
    user_id=50945

    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
    user_id=195958

    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.