[Python-ideas] Conventions for Python code documentation (was: PEP 484 (Type Hints) -- first draft round)

[Philipp A.]

I have am idea: how about including a @paramdoc decorator that accepts one
named string argument per parameter and appends information gathered via
type annotations and default values to the docstring?

E.g.

~~~~
@paramdoc(
    main_course="Meaty because our society is medieval",
    side_dish="Optional, meat is enough",
    __return__="Objective opinion")
def eat(main_course: Meat, side_dish=None: Food) -> Opinion:
    """
    Decides how well the meat and side dish taste together
    """
    ...
~~~~

After this, eat.__doc__ would be an object that retains the raw parts as
properties, but otherwise is an elongated version of the original
docstring. Its fourth and third to last line would read something like this:

~~~~
side_dish (Food; defaults to None):
    Optional, meat is enough
~~~~

What do you think?

Guido van Rossum <guido <guido at python.org>@ <guido at python.org>python.org
<guido at python.org>> schrieb am Mo., 19. Jan. 2015 20:56:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150119/6f817d5a/attachment.html>