Issue 15270: "Economy of Expression" section outdated (original) (raw)

This issue has been migrated to GitHub: https://github.com/python/cpython/issues/59475

classification

process

Created on 2012-07-07 06:03 by chris.jerdonek, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Messages (6)
msg164788 - (view)	Author: Chris Jerdonek (chris.jerdonek) *	Date: 2012-07-07 06:03
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.
msg164798 - (view)	Author: Antoine Pitrou (pitrou) *	Date: 2012-07-07 09:57
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.
msg164962 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2012-07-08 04:05
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.
msg171041 - (view)	Author: Ezio Melotti (ezio.melotti) *	Date: 2012-09-23 14:16
IMHO the paragraph about super() can be dropped altogether.
msg171057 - (view)	Author: Roundup Robot (python-dev)	Date: 2012-09-23 16:38
New changeset 100909b4def0 by Raymond Hettinger in branch 'default': Issue #15270. Appease critics by removing a reference to the docs for super(). http://hg.python.org/devguide/rev/100909b4def0
msg171058 - (view)	Author: Raymond Hettinger (rhettinger) *	Date: 2012-09-23 16:39
This whole discussion was inane.