From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 29 Aug 2019 08:02:58 +0000 (-0700)
Subject: bpo-23674:  Clarify ambiguities in super() docs (GH-15564) (GH-15586)
X-Git-Tag: v3.8.0b4~8
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=43b7ed77a8224c378b436ad3385733454198be41;p=thirdparty%2FPython%2Fcpython.git

bpo-23674:  Clarify ambiguities in super() docs (GH-15564) (GH-15586)

(cherry picked from commit cd81f0500fe98c7f4cddb06530fffabd14f036b8)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
---

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index c225f3dee921..c748b086d8ac 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1587,10 +1587,17 @@ are always available.  They are listed here in alphabetical order.
 
    Return a proxy object that delegates method calls to a parent or sibling
    class of *type*.  This is useful for accessing inherited methods that have
-   been overridden in a class. The search order is same as that used by
-   :func:`getattr` except that the *type* itself is skipped.
+   been overridden in a class.
 
-   The :attr:`~class.__mro__` attribute of the *type* lists the method
+   The *object-or-type* determines the :term:`method resolution order`
+   to be searched.  The search starts from the class right after the
+   *type*.
+
+   For example, if :attr:`~class.__mro__` of *object-or-type* is
+   ``D -> B -> C -> A -> object`` and the value of *type* is ``B``,
+   then :func:`super` searches ``C -> A -> object``.
+
+   The :attr:`~class.__mro__` attribute of the *object-or-type* lists the method
    resolution search order used by both :func:`getattr` and :func:`super`.  The
    attribute is dynamic and can change whenever the inheritance hierarchy is
    updated.