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

[Andrew Bennetts]

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.

[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]

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

[Andrew Bennetts]

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]

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.