"Economy of Expression" section outdated

[cjerdonek]

BPO	15270
Nosy	@rhettinger, @pitrou, @ezio-melotti, @merwok, @cjerdonek

^{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 = 'https://github.com/rhettinger'
closed_at = <Date 2012-09-23.16:39:41.343>
created_at = <Date 2012-07-07.06:03:48.864>
labels = ['easy', 'docs']
title = '"Economy of Expression" section outdated'
updated_at = <Date 2012-09-23.16:39:41.329>
user = 'https://github.com/cjerdonek'

bugs.python.org fields:

activity = <Date 2012-09-23.16:39:41.329>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2012-09-23.16:39:41.343>
closer = 'rhettinger'
components = ['Documentation', 'Devguide']
creation = <Date 2012-07-07.06:03:48.864>
creator = 'chris.jerdonek'
dependencies = []
files = []
hgrepos = []
issue_num = 15270
keywords = ['easy']
message_count = 6.0
messages = ['164788', '164798', '164962', '171041', '171057', '171058']
nosy_count = 8.0
nosy_names = ['rhettinger', 'pitrou', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'docs@python', 'tshepang', 'python-dev']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue15270'
versions = ['Python 3.3']

[cjerdonek]

The "Economy of Expression" section of the Dev Guide's "Documenting Python"--

http://docs.python.org/devguide/documenting.html#economy-of-expression

says, "The documentation for super() is an example of where a good deal of information was condensed into a few short paragraphs."

However, the documentation for super() is now nine short paragraphs. Back in Python 2.2 (when super() was introduced), the description really was only two short paragraphs (along with a brief code snippet):

http://docs.python.org/release/2.2.3/lib/built-in-funcs.html

So this might no longer be the best example.

[pitrou]

The super() doc is also a good example of unreadable jargon ("dynamic execution environment" ??). Nowhere is it obvious to a beginner what super() is *practically* used for.

[rhettinger]

The point was that the docs shouldn't "write a book" where briefer explanations suffice. The mention of super() may not be the best example because many "experts" still don't get what it is all about regardless of how much or how little much is written.

FWIW, the original two short paragraphs led to a good deal of confusion resulting in people declaring super() to be either inscrutable, unusable, or both.

[ezio-melotti]

IMHO the paragraph about super() can be dropped altogether.

[python-dev]

New changeset 100909b4def0 by Raymond Hettinger in branch 'default':
Issue bpo-15270. Appease critics by removing a reference to the docs for super().
http://hg.python.org/devguide/rev/100909b4def0

[rhettinger]

This whole discussion was inane.