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

Chris Barker chris.barker at noaa.gov
Tue Jan 20 17:33:46 CET 2015


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
>     """
>     ...
>
aside from my thoughts about this being an odd use of the decorator syntax,
I fail to see how this is better than simply putting the information in the
docstring itself? You still are putting information in two places, making
it easy for it to get out of sync, and I think it actually make sit harder
to read -- that could end up being one really big decorator.

-Chris



-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/a6f99ea1/attachment.html>


More information about the Python-ideas mailing list