[docs] [issue36913] Missing documentation for decorators

[Stéphane Wirtel]

Stéphane Wirtel <stephane at wirtel.be> added the comment:

Hi Tomer,

>Thank you for the quick response.
Welcome
>
>Are PEPs considered de-facto documentation for language features? For
>example, string formatting was described in PEP 3101, but still has
>sections in the documentation dedicated to it. I believe that
>decorators should get a similar treatment :-)
Good catch for the string formatting.

For the decorator, it's different because a decorator is mainly a
function taking a function and returning a function.

Example you can write this decorator:

def my_decorator(func):
    return func

def my_awesome_function(*args, **kwargs):
    print(args)
    print(kwargs)

    return 42

my_awesome_function = my_decorator(my_awesome_function)

in this case, we don't need to document the decorator.

for the '@' syntax, it's described in the doc but it's syntactic sugar
for the decorator. I don't think we need to add a big description for
that, because everything is described in the PEP.

I would like to have the opinion of the other core-dev. @sizeof?

>
>I also think that describing decorators as part of the grammar
>definition is lacking. Why is there a whole chapter for Errors and
>Exceptions and it's not only discussed under the grammar definition for
>raise?
>
>Decorators are a pretty unique (and cool!) feature of Python, and
>therefore new learners of the language need a better reference for
>learning about them.
>
>I realize that this is a big request, as you would need some expert to
>write this documentation.
You can open a PR ;-)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue36913>
_______________________________________