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

[Andrew Barnert]

On Jan 19, 2015, at 17:04, Chris Barker - NOAA Federal <chris.barker at noaa.gov> wrote:

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

But his paramdoc(…) is clearly a function that takes a function and returns a customized version of the function passed in--hence a decorator. And I don't know what distinction you're trying to make. I can guess at a few possibilities, but none of them work.

Sure, paramdoc itself is a function that takes some arguments and returns a decorator function, but the same is true for all kinds of things we normally call decorators, like lru_cache and partial.

And the function is customized by having a different doc string instead of, say, different parameter annotations or a closure that runs some extra code before the main code, but I don't see how that makes a difference.

And the decorator would likely be implemented by mutating and returning the function instead of creating and returning a wrapper, but that's just an implementation detail that's irrelevant to the user (and wraps and many other well-known decorators work that way).

> 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 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/
> _______________________________________________
> 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/2e86705e/attachment.html>