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

Guido van Rossum guido at python.org
Mon Jan 19 23:23:00 CET 2015


Try to implement it and see how well it works.

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

> 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:
>



-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150119/ac71125b/attachment.html>


More information about the Python-ideas mailing list