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

Philipp A. flying-sheep at web.de
Mon Jan 19 23:14:45 CET 2015

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?


    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>

More information about the Python-ideas mailing list