Repository navigation
Missing documentation for decorators #81094
Description
| BPO | 36913 |
|---|---|
| Nosy | @matrixise, @JulienPalard, @mblahay, @tomerv |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2019-05-14.07:35:28.614>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Missing documentation for decorators'
updated_at = <Date 2019-05-27.03:15:43.677>
user = 'https://github.com/tomerv'bugs.python.org fields:
activity = <Date 2019-05-27.03:15:43.677>
actor = 'mblahay'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-05-14.07:35:28.614>
creator = 'tomerv'
dependencies = []
files = []
hgrepos = []
issue_num = 36913
keywords = []
message_count = 5.0
messages = ['342435', '342436', '342437', '342438', '343604']
nosy_count = 5.0
nosy_names = ['docs@python', 'matrixise', 'mdk', 'mblahay', 'tomerv']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue36913'
versions = ['Python 3.7', 'Python 3.8']
Activity
tomerv commentedon May 14, 2019
The documentation for decorators (for methods and classes) is pretty lacking.
Searching for "decorator" ( https://docs.python.org/3/search.html?q=decorator ) brings up a lot of libraries that use decorators, but no documentation explaining what they are and how they work. The documentation should have a dedicated page for explaining decorators, and this should be the 1st search result.
--
In the meantime, then search should give as a 1st result a link to the definition of decorator in the glossary: https://docs.python.org/3.7/glossary.html#glossary
Actually, it seems that there is no way to directly link to a paragraph in the glossary - so that should be added as well.
In general, it would be nice if a search for some term X would show as a 1st result the definition of X in the glossary (if it exists there).
Thanks!
matrixise commentedon May 14, 2019
Hi,
Thank you for your feedback.
In fact, there is a limitation with the current search engine of Sphinx (because we use it for the documentation). For example, if you try to find the meaning of "for", for us it's a keyword but for the search engine, it will try to find all the sections containing "for" (formatter, platform, argparse.ArgumentParser.format_help, etc...).
For that, we could open an issue on the repository of Sphinx.
Now, about the decorators.
In the definition of a function, we explain the call of a decorator, See the grammar. https://docs.python.org/3/reference/compound_stmts.html#function-definitions
"""
A function definition may be wrapped by one or more decorator expressions. Decorator expressions are evaluated when the function is defined, in the scope that contains the function definition. The result must be a callable, which is invoked with the function object as the only argument. The returned value is bound to the function name instead of the function object. Multiple decorators are applied in a nested fashion. For example, the following code
"""
But because it's a specification of the language which has been described with 2 PEPs you can read it on the PEP Index page.
Function: https://www.python.org/dev/peps/pep-0318/
-> Introduced in 2.4 https://docs.python.org/3/whatsnew/2.4.html
Class: https://www.python.org/dev/peps/pep-3129/
-> Introduced in 3.0
Now, I suggest one thing, add a link to the PEPs in this section https://docs.python.org/3/reference/compound_stmts.html#function-definitions
tomerv commentedon May 14, 2019
Thank you for the quick response.
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 :-)
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.
matrixise commentedon May 14, 2019
Hi Tomer,
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:
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?
mblahay commentedon May 27, 2019
The PEP is not the first place I go looking for information on Python topics, just my two cents.
slateny commentedon Sep 1, 2022
It seems that the current search https://docs.python.org/3/search.html?q=decorator does point towards the glossary as the first search result.
The Class Definitions section does link PEP 3129 and also references PEP 318 so everything's technically in the doc, but as mentioned PEP 318 can also go under the box at the end of Function definitions for clarity.
Rasputin2 commentedon Dec 28, 2023
Hello, I am a first time contributor. If this is something that still needs assistance, I could start by just adding a description of decorators in the docs, see if you accept that, and then start drafting entries for each decorator one by one. This would be a good learning experience for me,. Not sure if this is still something you guys believed needed to be worked on or not.
hugovk commentedon Dec 28, 2023
Hello! I think all that's left is:
Would you like to open a PR?
Rasputin2 commentedon Dec 29, 2023
Rasputin2 commentedon Dec 29, 2023
Hi Hugo,
Sorry if I am being dense here, but this is my first contribution. First, I tried just editing the code on Codespace in Github and then I tried forking, cloning, and making the change. Either way, I cannot seem to "find" where the docs "are" in the code. In other words, I see this:
I don't actually 'see' the html for the docs that folks are referencing. I assume there is an html file somewhere for me to modify, but I cannot seem to find it. Apologies if this is a noob question, but I can't seem to see the next step here.
hugovk commentedon Dec 30, 2023
The HTML is generated from RST files.
If you go to https://docs.python.org/3/reference/compound_stmts.html#function-definitions and click Show Source in the left menu that takes you to https://github.com/python/cpython/blob/main/Doc/reference/compound_stmts.rst, which is the file to edit.
To generate the HTML:
cd Doc .\make htmlAnd open build/html/index.html
See also https://devguide.python.org/documentation/start-documenting/
Rasputin2 commentedon Dec 30, 2023
Rasputin2 commentedon Dec 30, 2023
Hi Hugo:
I believe I did this correctly (hopefully). A screenshot of the change and the github pull request are shown below:
gh-81094: Refer to PEP 318 in compound_statements.rst (#113588)
pythongh-81094: Refer to PEP 318 in compound_statements.rst (pythonGH…
pythongh-81094: Refer to PEP 318 in compound_statements.rst (pythonGH…
[3.11] gh-81094: Refer to PEP 318 in compound_statements.rst (GH-113588…
[3.12] gh-81094: Refer to PEP 318 in compound_statements.rst (GH-113588…
pythongh-81094: Refer to PEP 318 in compound_statements.rst (python#1…
pythongh-81094: Refer to PEP 318 in compound_statements.rst (python#1…
pythongh-81094: Refer to PEP 318 in compound_statements.rst (python#1…