Raymond Hettinger <raymond.hettin...@gmail.com> added the comment:
> "a base class ``B`` following ``A``" shouldn't it be "the base > class"? . After all, there is at most one base class following ``A`` No. There can be other classes in the chain. The first to match the lookup wins. > Also, it may help clarify to write "is an object `obj`" and > "is a type `type2`" so that it get clear what `obj` and `type2` means. Sorry, but I don't your proposed wording adds value. While you may feel that it is more precise, it just adds redundant words without adding information. FWIW, we do this all over the docs, letting parameter names such as *obj* and *type2* communicate that we're referring to an object or a type. > Hence, I believe that the parentheses should be removed after `m` I took care of that in the other tracker issue. That said, it arguably made the docs worse rather than better because by far the dominant use case for super() is calling methods rather than doing attribute lookup. I only made the change to be consistent with the other attribute lookup examples. > I find super documentation confusing because it uses multiple variables > that are never introduced. ISTM that you're looking for a full tutorial with fully worked worked out examples rather than English text interspersed with code snippets. Consider reading the super-considered-super post for that purpose. As for the existing text, I've wrestled with it for years and think we've hit a local optimum. Expanding the text with more steps and descriptions of each step results in documentation that causes people's eyes to glaze over and to miss the main point of each sentence. Also, remember that the documentation is factored. The descriptor tutorial is primarily about descriptors. A super() call is just one of four ways to invoke a descriptor. From a descriptor howto point-of-view, all we want to communicate is that the attribute/method search starts at the next in the mro rather than the current instance. It is not the goal of that section to fully document or discuss super(). As for the main super() docs, that is the place talk about how super works; however, it is not the job of that section to explain the rest of Python (terms like bound, unbound, etc). In a way, the only job of this section is to differentiate how ``super(A, a).x`` differs from ``a.x``. Other parts of the docs cover the general attribute lookup, C3 algorithm, method binding, etc. The use of super() is just a special case where where the search starts from the class right after the given or inferred *type* argument. ---------- nosy: +rhettinger _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue46182> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
