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

Chris Barker - NOAA Federal chris.barker at noaa.gov
Tue Jan 20 02:04:56 CET 2015

On Jan 19, 2015, at 2:16 PM, "Philipp A." <flying-sheep at web.de> wrote:

I have am idea: how about including a @paramdoc decorator

I always teach that the @ syntax is a decoration, not a decorator, whereas
a decorator is a function that takes a function and returns another
function ( usually a customized version of the passed in function). This
distinction between decorators and decoration syntax keeps the door open to
do just about anything with decorations, but am I the only one that thinks
it's a bad idea to have it be for "any old thing we want to hang off a

Let's keep decorations for decorators...


that accepts one named string argument per parameter and appends
information gathered via type annotations and default values to the


    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:

Python-ideas mailing list
Python-ideas at python.org
Code of Conduct: http://python.org/psf/codeofconduct/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150119/8df546cd/attachment.html>

More information about the Python-ideas mailing list