classification
Title: Please add a comprehensive index of decorators to the documentation.
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, r.david.murray, rhettinger, tom kronmiller
Priority: normal Keywords:

Created on 2017-06-27 14:23 by tom kronmiller, last changed 2017-06-30 15:42 by brett.cannon. This issue is now closed.

Messages (7)
msg297039 - (view) Author: tom kronmiller (tom kronmiller) Date: 2017-06-27 14:23
It is difficult to learn what decorators there are because there is no single index which lists all of them (at least, I have been unable to find one).  Instead, one must stumble across them while reading library module documentation.  An index listing the decorators with a short description would be really helpful (to me, at least).

Thanks.
msg297204 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-06-28 17:53
Why do you want an index of *just* decorators? The documentation is structured so you look for the module that probably contains a solution to your problem and then you see what the module may have (which may have a solution that isn't a decorator). Jumping straight to a list of just decorators means you would miss out on any other solution that happens to not be a decorator.
msg297243 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-06-29 02:14
This request doesn't make sense to me.  Decorators are an implementation technique and not really a topic unto themselves.

FWIW, Guido recently rejected a request to create a listing of all the command line tools.  Python docs are primarily organized by modules of related tools rather than by their implementation technique.
msg297295 - (view) Author: tom kronmiller (tom kronmiller) Date: 2017-06-29 19:08
I would not object if there was an index which contained the decorators among other things, but I have found it difficult in practice to discover things like @staticmethod and @contextmanager.  Just as I browse the index of library modules to for insight as to what it provides, I would like to browse the decorators for insight as to problems that have been solved using them.
msg297419 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-06-30 15:29
Hmm.  All the dunder methods are listed in the index on the '_' page.  It would kind of be consistent to have an '@' page.  Not sure what would be needed to make that happen though (might be a sphinx level thing).
msg297425 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-06-30 15:42
Both staticmethod and contextmanager are in the index under "S" and "C". But if you mean they were hard to discover, having them under a list of decorators wouldn't have necessarily helped since, as we pointed out, you may get misled to look for a decorator when in fact there was a better solution that wasn't a decorator.

I'm closing this as "not a bug" since listing everything twice -- once under its name and once under its type/expected usage -- is just going to lead to unwieldy lists that are ridiculously long that no one is going to peruse.
msg297426 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-06-30 15:42
And thanks for at least bringing the idea forward, Tom.
History
Date User Action Args
2017-06-30 15:42:53brett.cannonsetmessages: + msg297426
2017-06-30 15:42:18brett.cannonsetstatus: open -> closed
resolution: not a bug
messages: + msg297425

stage: resolved
2017-06-30 15:29:00r.david.murraysetnosy: + r.david.murray
messages: + msg297419
2017-06-29 19:08:05tom kronmillersetmessages: + msg297295
2017-06-29 02:14:46rhettingersetnosy: + rhettinger
messages: + msg297243
2017-06-28 17:53:25brett.cannonsetnosy: + brett.cannon
messages: + msg297204
2017-06-27 14:23:18tom kronmillercreate