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?