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

[Steven D'Aprano]

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

The docs do say what super does: it returns "a proxy object that delegates method calls to a parent or sibling class of type", just as you quoted. That concise description is (almost) completely accurate and precise.

(I say *almost* because it's not just method calls that it works with, but any attribute lookup.)

What more do you want? That's not a rhetorical question.

I'm not saying that the docs are perfect or cannot be improved, but they look pretty good to me: they tell you what super does, they tell you why you might use it, and show how to use it. What's missing? Again, not a rhetorical question.

I understand that super is a very advanced corner of the language: there's a lot of necessary technical jargon in the docs, e.g.:

- One already needs to have a good understanding of what super *does* in order to make sense of the sentence describing what it *is*, so there's an element of circular reasoning needed.

- The reader needs to understand that super isn't magical, it just returns an object like any other function, and understand what "proxy object" means, as well as delegation.

- And have an understanding of how inheritance and the MRO work in Python, and the difference between bound and unbound methods/proxies.

I think that to the experienced reader who knows these concepts, the docs should be pretty clear and complete.

I'm having a hard time seeing what you believe is missing from the docs. Can you explain further?

Perhaps there ought to be a "gentle guide to super" somewhere, and the docs could link to that?

----------

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