Multiple clean-ups to the docs for builtin functions.

* Use concrete example for dir() and eliminate the distracting doctest directives.
* Add a pure python equivalent for enumerate()
* Modify the enumerate() example to demonstrate the start argument
* Remove incorrect reference the *iterable* in the enumerate() docs.
* Downgrade the comments on input() from a warning to a note.
* Fix the iter() example to use the empty string as the terminating
  condition for file.readline().  Also, the old example was broken
  because readline() results include a newline, so 'STOP\n' would have
  been the correct terminating condition.  Even with that fix, the
  STOP example was fragile and would have lead to infinite loops with
  malformed inputs.
* Do not refer to classmethod as being "more advanced" than staticmethod.

1 files changed, 34 insertions, 28 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1c6c76a..7a3a2d5 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -298,19 +298,19 @@ available.  They are listed here in alphabetical order.
    The resulting list is sorted alphabetically.  For example:
 
       >>> import struct
-      >>> dir()   # doctest: +SKIP
+      >>> dir()   # show the names in the module namespace
       ['__builtins__', '__doc__', '__name__', 'struct']
-      >>> dir(struct)   # doctest: +NORMALIZE_WHITESPACE
+      >>> dir(struct)   # show the names in the struct module
       ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
        '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
        'unpack', 'unpack_from']
-      >>> class Foo(object):
-      ...     def __dir__(self):
-      ...         return ["kan", "ga", "roo"]
-      ...
-      >>> f = Foo()
+      >>> class Shape(object):
+              def __dir__(self):
+                  return ['area', 'perimter', 'location']
+
+      >>> f = Shape()
       >>> dir(f)
-      ['ga', 'kan', 'roo']
+      ['area', 'perimter', 'location']
 
    .. note::
 
@@ -342,16 +342,22 @@ available.  They are listed here in alphabetical order.
    :term:`iterator`, or some other object which supports iteration.  The
    :meth:`!next` method of the iterator returned by :func:`enumerate` returns a
    tuple containing a count (from *start* which defaults to 0) and the
-   corresponding value obtained from iterating over *iterable*.
-   :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
-   ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
+   corresponding value obtained from iterating over *sequence*::
+
+      >>> for i, season in enumerate('Spring Summer Fall Winter'.split(), start=1):
+              print i, season
+      1 Spring
+      2 Summer
+      3 Fall
+      4 Winter
 
-      >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
-      ...     print i, season
-      0 Spring
-      1 Summer
-      2 Fall
-      3 Winter
+   Equivalent to::
+
+      def enumerate(sequence, start=0):
+          n = start
+          for elem in sequence:
+              yield n, elem
+              n += 1
 
    .. versionadded:: 2.3
    .. versionadded:: 2.6
@@ -586,13 +592,12 @@ available.  They are listed here in alphabetical order.
 
    Equivalent to ``eval(raw_input(prompt))``.
 
-   .. warning::
+   .. note::
 
-      This function is not safe from user errors!  It expects a valid Python
-      expression as input; if the input is not syntactically valid, a
-      :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
-      error during evaluation.  (On the other hand, sometimes this is exactly what you
-      need when writing a quick script for expert use.)
+      This function does not catch user errors.  It expects a valid Python
+      expression as input. If the input is not syntactically valid, a
+      :exc:`SyntaxError` will be raised. Other exceptions may be raised if there
+      is an error during evaluation.
 
    If the :mod:`readline` module was loaded, then :func:`input` will use it to
    provide elaborate line editing and history features.
@@ -660,10 +665,10 @@ available.  They are listed here in alphabetical order.
 
    One useful application of the second form of :func:`iter` is to read lines of
    a file until a certain line is reached.  The following example reads a file
-   until ``"STOP"`` is reached: ::
+   until the :meth:`readline` method returns an empty string::
 
-      with open("mydata.txt") as fp:
-          for line in iter(fp.readline, "STOP"):
+      with open('mydata.txt') as fp:
+          for line in iter(fp.readline, ''):
               process_line(line)
 
    .. versionadded:: 2.2
@@ -1241,8 +1246,9 @@ available.  They are listed here in alphabetical order.
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class.
 
-   Static methods in Python are similar to those found in Java or C++. For a more
-   advanced concept, see :func:`classmethod` in this section.
+   Static methods in Python are similar to those found in Java or C++. Also see
+   :func:`classmethod` for a variant that is useful for creating alternate
+   class constructors.
 
    For more information on static methods, consult the documentation on the
    standard type hierarchy in :ref:`types`.