diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 97209a4c08f..62b37c08c5d 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1025,25 +1025,31 @@ available.  They are listed here in alphabetical order.
    sequence of strings is by calling ``''.join(sequence)``.
 
 
-.. function:: super(type[, object-or-type])
+.. function:: super([type[, object-or-type]])
 
-   .. XXX need to document PEP "new super"
+   .. XXX updated as per http://www.artima.com/weblogs/viewpost.jsp?thread=208549 but needs checking
 
-   Return the superclass 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 the second argument is a type,
+   Return the superclass of *type*.
+   
+   Calling :func:`super()` without arguments is equivalent to
+   ``super(this_class, first_arg)``. If called with one
+   argument the super object returned is unbound.  If called with two
+   arguments and the second argument is an object, ``isinstance(obj,
+   type)`` must be true.  If the second argument is a type,
    ``issubclass(type2, type)`` must be true.
 
    A typical use for calling a cooperative superclass method is::
 
       class C(B):
-          def meth(self, arg):
-              super(C, self).meth(arg)
+          def method(self, arg):
+              super().method(arg)    # This does the same thing as: super(C, self).method(arg)
 
    Note that :func:`super` is implemented as part of the binding process for
-   explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
+   explicit dotted attribute lookups such as ``super().__getitem__(name)``.
    Accordingly, :func:`super` is undefined for implicit lookups using statements or
-   operators such as ``super(C, self)[name]``.
+   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.
 
 
 .. function:: tuple([iterable])