Inconsistent documentation around decorators

[dmiyakawa]

BPO	31567
Nosy	@merwok, @berkerpeksag, @dmiyakawa, @cryvate
PRs	bpo-31567: Use decorator markup for staticmethod()/classmethod() #3959 [3.6] bpo-31567: add or fix decorator markup in docs (GH-3959) (GH-3966)  #3965 bpo-31567: fix more decorator markup in docs (GH-3959) #3966

^{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 = <Date 2017-10-12.16:34:21.205>
created_at = <Date 2017-09-24.07:31:30.261>
labels = ['type-bug', '3.7', 'docs']
title = 'Inconsistent documentation around decorators'
updated_at = <Date 2017-10-12.16:34:21.204>
user = 'https://github.com/dmiyakawa'

bugs.python.org fields:

activity = <Date 2017-10-12.16:34:21.204>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-10-12.16:34:21.205>
closer = 'eric.araujo'
components = ['Documentation']
creation = <Date 2017-09-24.07:31:30.261>
creator = 'dmiyakawa'
dependencies = []
files = []
hgrepos = []
issue_num = 31567
keywords = ['patch']
message_count = 9.0
messages = ['302830', '303557', '304244', '304246', '304257', '304261', '304267', '304268', '304269']
nosy_count = 5.0
nosy_names = ['eric.araujo', 'docs@python', 'berker.peksag', 'dmiyakawa', 'cryvate']
pr_nums = ['3959', '3965', '3966']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue31567'
versions = ['Python 3.6', 'Python 3.7']

[dmiyakawa]

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 @

[merwok]

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)

[merwok]

New changeset 0e61e67 by Éric Araujo (Daisuke Miyakawa) in branch 'master':
bpo-31567: add or fix decorator markup in docs (bpo-3959)
0e61e67

[berkerpeksag]

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.

[merwok]

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?

[berkerpeksag]

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.

[merwok]

New changeset 03b9537 by Éric Araujo in branch 'master':
bpo-31567: more decorator markup fixes in docs (GH-3959) (bpo-3966)
03b9537

[merwok]

New changeset 205dd4e 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)
205dd4e

[merwok]

Cheers!