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

[Chris Barker - NOAA Federal]

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
function"?

Let's keep decorations for decorators...

-Chris


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:

_______________________________________________
Python-ideas mailing list
Python-ideas at python.org
https://mail.python.org/mailman/listinfo/python-ideas
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>