bpo-31567: Use decorator markup for staticmethod()/classmethod()

[dmiyakawa]

staticmethod() and classmethod() are expected to be used with decorator, so documentation should mention it.

https://bugs.python.org/issue31567

[merwok]

I suspect that this should be decorator: classmethod; the version with arguments is probably used for functions that are decorator factories.

(For example, @functools.lru_cache(max_size=20) gets arguments and returns a decorator which is then applied to the decorated function; the markup must show clearly if people are expected to call @decorator or @decorator_factory().)

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[dmiyakawa]

I have made the requested changes; please review again.

Removed "(function)" for both classmethod and staticmethod. Since the following explanations points to the name "function" in the arg, I modified the description too (I mimicked the line in @functools.singledispatch)

https://docs.python.org/3.6/library/functools.html#functools.singledispatch

Transforms a function into a single-dispatch generic function.

[bedevere-bot]

Thanks for making the requested changes!

@merwok: please review the changes made to this pull request.

[merwok]

Thanks! Sphinx docs for the reference: http://www.sphinx-doc.org/en/1.6.4/domains.html#directive-py:decorator

I found three misuses of the markup (including singledispatch!) which I will fix in this PR, given that the original ticket was not only about staticmethod and classmethod.

[merwok]

I wasn’t able to push my commit to your fork (I expected that to be possible given that I could add a commit within github), and I can’t find your fork in the widget to create cross-forks PRs.

https://help.github.com/articles/committing-changes-to-a-pull-request-branch-created-from-a-fork/

[dmiyakawa]

Sorry I'm not sure what is going on...

I can see you actually added some changes in my PR, I I understand you can add more commits here
dmiyakawa@9b806c1

"Allow edits from maintainers" check in this page looks already on.
https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/

[merwok]

Yes that’s the one in created from github. I made another commit on my laptop and can’t push it to your fork or make a PR: merwok@59bc4a7

[dmiyakawa]

Tried merging the change in merwok/cpython to dmiyakawa/cpython.

[miss-islington]

Thanks @dmiyakawa for the PR, and @merwok for merging it 🌮🎉.. I'm working now to backport this PR to: 2.7, 3.6.
🐍🍒⛏🤖

[bedevere-bot]

GH-3965 is a backport of this pull request to the 3.6 branch.

[miss-islington]

Sorry, @dmiyakawa and @merwok, I could not cleanly backport this to 2.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 0e61e67a57deb4abc677808201d7cf3c38138e02 2.7

[merwok]

I’ll leave 2.7 alone, nothing already uses the decorator markup (maybe it’s not even supported in the sphinx version used by 2.7).

[merwok]

FTR I think the push issue was due to using an https URL for your fork rather than ssh!
I just pushed commits to the backport PR owned by the miss-islington bot.