[docs] [issue37176] super() docs don't say what super() does

[Steven D'Aprano]

Steven D'Aprano <steve+python at pearwood.info> added the comment:

> If you have to explain in a bpo issue how the doc should be read, that 
> proves exactly my point that it's confusing. The fact that it's 
> technically correct if you read it the right way is irrelevant.

Do you expect the docs to be technically correct when read wrongly? How 
else should people read the docs, except the right way?

If you have *concrete* suggestions for improvements, of course we will 
consider them. I'll start with two concrete improvements:

1. Explicitly document that the zero-argument version is equivalent
to super(__class__, <first argument (usually self)>), and note that 
__class__ here is a special variable populated by the compiler.

The first part of this is already documented in super.__doc__ and the 
second part used to be documented:

https://docs.python.org/3.1/library/functions.html?#super

and I don't think there's any harm in adding it back in.

2. Link to the essay on how the MRO is calculated.

https://www.python.org/download/releases/2.3/mro/

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37176>
_______________________________________