[Python-checkins] r67625 - python/branches/release30-maint/Doc/library/functions.rst

[raymond.hettinger]

Author: raymond.hettinger
Date: Sun Dec  7 02:24:52 2008
New Revision: 67625

Log:
Backport r67607 for Issue 1163367:  Clarify docs for super().

Modified:
   python/branches/release30-maint/Doc/library/functions.rst

Modified: python/branches/release30-maint/Doc/library/functions.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/functions.rst	(original)
+++ python/branches/release30-maint/Doc/library/functions.rst	Sun Dec  7 02:24:52 2008
@@ -1090,9 +1090,7 @@
 
 .. function:: super([type[, object-or-type]])
 
-   .. XXX updated as per http://www.artima.com/weblogs/viewpost.jsp?thread=208549 but needs checking
-
-   Return a "super" object that acts like the superclass of *type*.
+   Return a *super* object that acts as a proxy to superclasses of *type*.
 
    If the second argument is omitted the super object returned is unbound.  If
    the second argument is an object, ``isinstance(obj, type)`` must be true.  If
@@ -1100,8 +1098,8 @@
    Calling :func:`super` without arguments is equivalent to ``super(this_class,
    first_arg)``.
 
-   There are two typical use cases for "super".  In a class hierarchy with
-   single inheritance, "super" can be used to refer to parent classes without
+   There are two typical use cases for :func:`super`.  In a class hierarchy with
+   single inheritance, :func:`super` can be used to refer to parent classes without
    naming them explicitly, thus making the code more maintainable.  This use
    closely parallels the use of "super" in other programming languages.
    
@@ -1125,9 +1123,12 @@
    It does so by implementing its own :meth:`__getattribute__` method for searching
    parent classes in a predictable order that supports cooperative multiple inheritance.
    Accordingly, :func:`super` is undefined for implicit lookups using statements or
-   operators such as ``super()[name]``. Also, :func:`super` is not
-   limited to use inside methods: under the hood it searches the stack
-   frame for the class (``__class__``) and the first argument.
+   operators such as ``super()[name]``.
+
+   Also note that :func:`super` is not limited to use inside methods.  The
+   two argument specifies the arguments exactly and makes the appropriate
+   references.  The zero argument form automatically searches the stack frame
+   for the class (``__class__``) and the first argument.
 
 
 .. function:: tuple([iterable])