#62 Improved output for keyword arguments

[Paul E.C. Melis]

The current support (3.0 beta1) for describing optional keyword arguments seems to be ok (example from the epydoc docs):

def plant(seed, *tools, **options):
"""
@param seed: The seed that should be planted.
@param tools: Tools that should be used to plant the seed.
@param options: Any extra options for the planting.

@keyword dig_deep: Plant the seed deep under ground.
@keyword soak: Soak the seed before planting it.
"""

...

But the html output for this is

plant(seed, *tools, **options)
...

Parameters:

* seed - The seed that should be planted.
* tools - Tools that should be used to plant the seed.
* options - Any extra options for the planting.
* dig_deep - Plant the seed deep under ground.
* soak - Soak the seed before planting it.

Here, the distinction between mandatory arguments and optional keyword arguments is lost, which makes the documentation harder to comprehend.

Also, I think the suggestion to include the keyword argument parameter 'options' isn't very useful, as you'll never use the argument name 'options' as a keyword argument to plant().

I would suggest the following output (and leaving out the "@param options ..." part in the docstring):

plant(seed, *tools, **options)
...

Parameters:
* seed - The seed that should be planted.
* tools - Tools that should be used to plant the seed.

Optional keyword parameters:
* dig_deep - Plant the seed deep under ground.
* soak - Soak the seed before planting it.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

I wouldn't mind doing something like this, but it should be noted that just because a parameter is a keyword parameter, doesn't always mean it's optional. E.g., a library may expect all parameters to be given by name (not positionally), but still insist that certain parameters be present.

As always, patches are welcome. :)