classification
Title: Inconsistent documentation around decorators
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Henk-Jaap Wagenaar, berker.peksag, dmiyakawa, docs@python, eric.araujo
Priority: normal Keywords: patch

Created on 2017-09-24 07:31 by dmiyakawa, last changed 2017-10-12 16:34 by eric.araujo. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 3959 merged dmiyakawa, 2017-10-12 01:38
PR 3965 merged python-dev, 2017-10-12 14:40
PR 3966 merged eric.araujo, 2017-10-12 15:10
Messages (9)
msg302830 - (view) Author: Daisuke Miyakawa (dmiyakawa) * Date: 2017-09-24 07:31
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 @
msg303557 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-02 18:47
> 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)
msg304244 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-12 14:39
New changeset 0e61e67a57deb4abc677808201d7cf3c38138e02 by Éric Araujo (Daisuke Miyakawa) in branch 'master':
bpo-31567: add or fix decorator markup in docs (#3959)
https://github.com/python/cpython/commit/0e61e67a57deb4abc677808201d7cf3c38138e02
msg304246 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-12 14:48
Use of classmethod and staticmethod decorators as functions is still a valid use case. I think the old signatures should be kept. It should be possible to document both uses in same place:

    .. function:: classmethod(function)
    .. decorator:: classmethod

       Documentation body.
msg304257 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-12 15:29
I think existing uses of the decorator markup rely on the reader’s understanding that it’s syntactic sugar for a call and an assignment, and they don’t have decorator+function markup.  The PRs for this ticket follow that.

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?
msg304261 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-12 15:46
> 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.
msg304267 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-12 16:28
New changeset 03b9537dc515d10528f83c920d38910b95755aff by Éric Araujo in branch 'master':
bpo-31567: more decorator markup fixes in docs (GH-3959) (#3966)
https://github.com/python/cpython/commit/03b9537dc515d10528f83c920d38910b95755aff
msg304268 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-12 16:33
New changeset 205dd4e14de77f9c8ed2903ddebbcf9968bbb6a9 by Éric Araujo (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966)
https://github.com/python/cpython/commit/205dd4e14de77f9c8ed2903ddebbcf9968bbb6a9
msg304269 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-10-12 16:34
Cheers!
History
Date User Action Args
2017-10-12 16:34:21eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg304269

stage: patch review -> resolved
2017-10-12 16:33:07eric.araujosetmessages: + msg304268
2017-10-12 16:28:59eric.araujosetmessages: + msg304267
2017-10-12 15:46:54berker.peksagsetmessages: + msg304261
2017-10-12 15:29:25eric.araujosetmessages: + msg304257
2017-10-12 15:10:13eric.araujosetpull_requests: + pull_request3945
2017-10-12 14:48:33berker.peksagsetnosy: + berker.peksag
messages: + msg304246
2017-10-12 14:40:40python-devsetpull_requests: + pull_request3944
2017-10-12 14:39:45eric.araujosetmessages: + msg304244
2017-10-12 01:38:32dmiyakawasetkeywords: + patch
stage: patch review
pull_requests: + pull_request3935
2017-10-03 14:35:54Henk-Jaap Wagenaarsetnosy: + Henk-Jaap Wagenaar
2017-10-02 18:47:07eric.araujosetnosy: + eric.araujo
messages: + msg303557
2017-09-24 07:31:30dmiyakawacreate