Repository navigation
Please add a comprehensive index of decorators to the documentation. #74970
Description
| BPO | 30787 |
|---|---|
| Nosy | @brettcannon, @rhettinger, @bitdancer |
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-06-30.15:42:18.432>
created_at = <Date 2017-06-27.14:23:18.617>
labels = ['invalid', 'type-feature', '3.7', 'docs']
title = 'Please add a comprehensive index of decorators to the documentation.'
updated_at = <Date 2017-06-30.15:42:53.300>
user = 'https://bugs.python.org/tomkronmiller'bugs.python.org fields:
activity = <Date 2017-06-30.15:42:53.300>
actor = 'brett.cannon'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-06-30.15:42:18.432>
closer = 'brett.cannon'
components = ['Documentation']
creation = <Date 2017-06-27.14:23:18.617>
creator = 'tom kronmiller'
dependencies = []
files = []
hgrepos = []
issue_num = 30787
keywords = []
message_count = 7.0
messages = ['297039', '297204', '297243', '297295', '297419', '297425', '297426']
nosy_count = 5.0
nosy_names = ['brett.cannon', 'rhettinger', 'r.david.murray', 'docs@python', 'tom kronmiller']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue30787'
versions = ['Python 3.6', 'Python 3.7']
Activity
tomkronmiller commentedon Jun 27, 2017
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.
brettcannon commentedon Jun 28, 2017
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.
rhettinger commentedon Jun 29, 2017
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.
tomkronmiller commentedon Jun 29, 2017
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.
bitdancer commentedon Jun 30, 2017
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).
brettcannon commentedon Jun 30, 2017
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.
brettcannon commentedon Jun 30, 2017
And thanks for at least bringing the idea forward, Tom.