[issue19931] namedtuple docstrings are verbose for no added benefit
Raymond Hettinger added the comment: I don't think we should strip-out all the docstrings because you're unhappy with automatically (mindlessly) generated documentation. What you really need is more control over the documentation tool (the ability to save how much detail you want, particularly with subclasses of builtins which have a ton of methods with simplistic docstrings and with abstract base classes). The docstring for __repr__ isn't especially useful but it is a key feature of a namedtuple. The docstring for __getnewargs__ is informative especially if you're subclassing a named tuple and need to know what it is used for. The docstring for the individual property attributes doesn't look helpful when you list them all but does add information for one-at-a-time help, such as help(Key.blockscope), or for tooltips. FWIW, there is also a proposal to make it easier to custom the default docstrings for the properties (to turn it into more of a data dictionary). -- assignee: docs@python - rhettinger resolution: - rejected status: open - closed versions: -Python 2.7, Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue19931 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue19931] namedtuple docstrings are verbose for no added benefit
Changes by Mark Lawrence breamore...@yahoo.co.uk: -- assignee: - docs@python components: +Documentation nosy: +docs@python type: - enhancement versions: +Python 3.4, Python 3.5 -Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue19931 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue19931] namedtuple docstrings are verbose for no added benefit
New submission from Ned Batchelder: When I make a namedtuple, I get automatic docstrings that use a lot of words to say very little. Sphinx autodoc produces this: ``` class Key Key(scope, user_id, block_scope_id, field_name) __getnewargs__() Return self as a plain tuple. Used by copy and pickle. __repr__() Return a nicely formatted representation string block_scope_id None Alias for field number 2 field_name None Alias for field number 3 scope None Alias for field number 0 user_id None Alias for field number 1 ``` The individual property docstrings offer no new information over the summary at the top. I'd like namedtuple to be not so verbose where it has no useful information to offer. The one-line summary is all the information namedtuple has, so that is all it should include in the docstring: ``` class Key Key(scope, user_id, block_scope_id, field_name) ``` -- components: Library (Lib) messages: 205584 nosy: nedbat priority: normal severity: normal status: open title: namedtuple docstrings are verbose for no added benefit versions: Python 2.7, Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue19931 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue19931] namedtuple docstrings are verbose for no added benefit
Changes by Serhiy Storchaka storch...@gmail.com: -- nosy: +rhettinger ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue19931 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
