[issue31567] Inconsistent documentation around decorators
New submission from Daisuke Miyakawa:
I can see inconsistency in library documentation around functions that are suitable for decorators. I'd like to clarify if it is based on my misunderstanding, or a real documentation problem.
Examples:
- https://docs.python.org/3/library/functions.html#staticmethod
- https://docs.python.org/3/library/functools.html#functools.lru_cache
Both staticmethod() and functools.lru_cache() are used with decorator expressions, while they have slightly different explanations.
The first one looks like just a usual function while the detailed explanations say it is used with decorator expression. The second one is what I don't understand; it says "@functools.lru_cache()", where the function name is "decorated" with @ in the doc. What does @ mean here? If there's some meaning, the next question is, why doc for staticmethod()
(and classmethod() in the same page) does not have it?
I don't know which is better, but I believe consistency is good. Some other examples :
- https://docs.python.org/3/library/contextlib.html?highlight=decorator -> @ here
- https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch -> no @ here
- https://docs.python.org/2.7/library/functools.html#functools.lru_cache -> Old functools does not have @
----------
assignee: docs@python
components: Documentation
messages: 302830
nosy: dmiyakawa, docs@python
priority: normal
severity: normal
status: open
title: Inconsistent documentation around decorators
type: behavior
versions: Python 3.6, Python 3.7
_______________________________________
Python tracker
Éric Araujo
What does @ mean here? If there's some meaning, the next question is, why doc for staticmethod() (and classmethod() in the same page) does not have it?
@ means that the function is meant to be used as a decorator (the markup looks like the actual code).
staticmethod and classmethod are older than the decorator syntax, which is older than the special sphinx markup for decorators (they used to just use the function markup).
For unittest.mock.patch, its result can be used as a decorator or as a context manager, so the current markup (no @) makes sense.
If you want to update staticmethod and classmethod to use the decorator markup, please send a pull request! (more info in the devguide)
----------
nosy: +merwok
_______________________________________
Python tracker
Change by Henk-Jaap Wagenaar
Change by Daisuke Miyakawa
Éric Araujo
Change by Roundup Robot
Berker Peksag
Change by Éric Araujo
Éric Araujo
Berker Peksag
That said, staticmethod as a non-decorator has an important use case for function injection in tests (using self.func in TestCase classes that work with a C module and an equivalent Python version). Maybe this deserves an extra example?
Yes, that would be nice.
----------
_______________________________________
Python tracker
Éric Araujo
Éric Araujo
Éric Araujo
participants (5)
-
Berker Peksag -
Daisuke Miyakawa
-
Henk-Jaap Wagenaar
-
Roundup Robot
-
Éric Araujo