Merge __next__ method link fixes with 3.2.

10 files changed, 61 insertions, 56 deletions

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 68dc3b7..35bdb96 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -365,7 +365,7 @@ Glossary
 
    iterator
       An object representing a stream of data.  Repeated calls to the iterator's
-      :meth:`__next__` method (or passing it to the built-in function
+      :meth:`~iterator.__next__` method (or passing it to the built-in function
       :func:`next`) return successive items in the stream.  When no more data
       are available a :exc:`StopIteration` exception is raised instead.  At this
       point, the iterator object is exhausted and any further calls to its
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index a88f10c..8908542 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -42,12 +42,13 @@ Executor Objects
 
        Equivalent to ``map(func, *iterables)`` except *func* is executed
        asynchronously and several calls to *func* may be made concurrently.  The
-       returned iterator raises a :exc:`TimeoutError` if :meth:`__next__()` is
-       called and the result isn't available after *timeout* seconds from the
-       original call to :meth:`Executor.map`. *timeout* can be an int or a
-       float.  If *timeout* is not specified or ``None``, there is no limit to
-       the wait time.  If a call raises an exception, then that exception will
-       be raised when its value is retrieved from the iterator.
+       returned iterator raises a :exc:`TimeoutError` if
+       :meth:`~iterator.__next__` is called and the result isn't available
+       after *timeout* seconds from the original call to :meth:`Executor.map`.
+       *timeout* can be an int or a float.  If *timeout* is not specified or
+       ``None``, there is no limit to the wait time.  If a call raises an
+       exception, then that exception will be raised when its value is
+       retrieved from the iterator.
 
     .. method:: shutdown(wait=True)
 
@@ -364,10 +365,11 @@ Module Functions
    different :class:`Executor` instances) given by *fs* that yields futures as
    they complete (finished or were cancelled).  Any futures that completed
    before :func:`as_completed` is called will be yielded first.  The returned
-   iterator raises a :exc:`TimeoutError` if :meth:`__next__` is called and the
-   result isn't available after *timeout* seconds from the original call to
-   :func:`as_completed`.  *timeout* can be an int or float.  If *timeout* is not
-   specified or ``None``, there is no limit to the wait time.
+   iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is
+   called and the result isn't available after *timeout* seconds from the
+   original call to :func:`as_completed`.  *timeout* can be an int or float.
+   If *timeout* is not specified or ``None``, there is no limit to the wait
+   time.
 
 
 .. seealso::
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 6d08a0c..854c521 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -660,10 +660,10 @@ the more significant byte last.
 
 .. opcode:: FOR_ITER (delta)
 
-   ``TOS`` is an :term:`iterator`.  Call its :meth:`__next__` method.  If this
-   yields a new value, push it on the stack (leaving the iterator below it).  If
-   the iterator indicates it is exhausted ``TOS`` is popped, and the byte code
-   counter is incremented by *delta*.
+   ``TOS`` is an :term:`iterator`.  Call its :meth:`~iterator.__next__` method.
+   If this yields a new value, push it on the stack (leaving the iterator below
+   it).  If the iterator indicates it is exhausted ``TOS`` is popped, and the
+   byte code counter is incremented by *delta*.
 
 
 .. opcode:: LOAD_GLOBAL (namei)
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 6ba58d4..ac02215 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -275,8 +275,8 @@ The following exceptions are the exceptions that are usually raised.
 .. exception:: StopIteration
 
    Raised by built-in function :func:`next` and an :term:`iterator`\'s
-   :meth:`__next__` method to signal that there are no further items to be
-   produced by the iterator.
+   :meth:`~iterator.__next__` method to signal that there are no further
+   items produced by the iterator.
 
    The exception object has a single attribute :attr:`value`, which is
    given as an argument when constructing the exception, and defaults
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 0e836f9..f782655 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -352,10 +352,10 @@ are always available.  They are listed here in alphabetical order.
 .. function:: enumerate(iterable, start=0)
 
    Return an enumerate object. *iterable* must be a sequence, an
-   :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
-   values obtained from iterating over *iterable*.
+   :term:`iterator`, or some other object which supports iteration.
+   The :meth:`~iterator.__next__` method of the iterator returned by
+   :func:`enumerate` returns a tuple containing a count (from *start* which
+   defaults to 0) and the values obtained from iterating over *iterable*.
 
       >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
       >>> list(enumerate(seasons))
@@ -687,9 +687,10 @@ are always available.  They are listed here in alphabetical order.
    starting at ``0``).  If it does not support either of those protocols,
    :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
    then *object* must be a callable object.  The iterator created in this case
-   will call *object* with no arguments for each call to its :meth:`__next__`
-   method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
-   will be raised, otherwise the value will be returned.
+   will call *object* with no arguments for each call to its
+   :meth:`~iterator.__next__` method; if the value returned is equal to
+   *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+   be returned.
 
    See also :ref:`typeiter`.
 
@@ -785,9 +786,9 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: next(iterator[, default])
 
-   Retrieve the next item from the *iterator* by calling its :meth:`__next__`
-   method.  If *default* is given, it is returned if the iterator is exhausted,
-   otherwise :exc:`StopIteration` is raised.
+   Retrieve the next item from the *iterator* by calling its
+   :meth:`~iterator.__next__` method.  If *default* is given, it is returned
+   if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
 
 
 .. function:: object()
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 759206b..e45dd30 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -779,9 +779,9 @@ specific sequence types, dictionaries, and other more specialized forms.  The
 specific types are not important beyond their implementation of the iterator
 protocol.
 
-Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must
-continue to do so on subsequent calls.  Implementations that do not obey this
-property are deemed broken.
+Once an iterator's :meth:`~iterator.__next__` method raises
+:exc:`StopIteration`, it must continue to do so on subsequent calls.
+Implementations that do not obey this property are deemed broken.
 
 
 .. _generator-types:
@@ -792,7 +792,8 @@ Generator Types
 Python's :term:`generator`\s provide a convenient way to implement the iterator
 protocol.  If a container object's :meth:`__iter__` method is implemented as a
 generator, it will automatically return an iterator object (technically, a
-generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods.
+generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
+methods.
 More information about generators can be found in :ref:`the documentation for
 the yield expression <yieldexpr>`.
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 57a0d79..d093383 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -600,9 +600,9 @@ Callable types
       A function or method which uses the :keyword:`yield` statement (see section
       :ref:`yield`) is called a :dfn:`generator function`.  Such a function, when
       called, always returns an iterator object which can be used to execute the
-      body of the function:  calling the iterator's :meth:`__next__` method will
-      cause the function to execute until it provides a value using the
-      :keyword:`yield` statement.  When the function executes a
+      body of the function:  calling the iterator's :meth:`iterator__next__`
+      method will cause the function to execute until it provides a value
+      using the :keyword:`yield` statement.  When the function executes a
       :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
       exception is raised and the iterator will have reached the end of the set of
       values to be returned.
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 364135a..41523cb 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -294,13 +294,13 @@ for comprehensions, except that it is enclosed in parentheses instead of
 brackets or curly braces.
 
 Variables used in the generator expression are evaluated lazily when the
-:meth:`__next__` method is called for generator object (in the same fashion as
-normal generators).  However, the leftmost :keyword:`for` clause is immediately
-evaluated, so that an error produced by it can be seen before any other possible
-error in the code that handles the generator expression.  Subsequent
-:keyword:`for` clauses cannot be evaluated immediately since they may depend on
-the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y
-in bar(x))``.
+:meth:`~generator.__next__` method is called for generator object (in the same
+fashion as normal generators).  However, the leftmost :keyword:`for` clause is
+immediately evaluated, so that an error produced by it can be seen before any
+other possible error in the code that handles the generator expression.
+Subsequent :keyword:`for` clauses cannot be evaluated immediately since they
+may depend on the previous :keyword:`for` loop. For example: ``(x*y for x in
+range(10) for y in bar(x))``.
 
 The parentheses can be omitted on calls with only one argument.  See section
 :ref:`calls` for the detail.
@@ -394,10 +394,11 @@ is already executing raises a :exc:`ValueError` exception.
 
    Starts the execution of a generator function or resumes it at the last
    executed :keyword:`yield` expression.  When a generator function is resumed
-   with a :meth:`__next__` method, the current :keyword:`yield` expression
-   always evaluates to :const:`None`.  The execution then continues to the next
-   :keyword:`yield` expression, where the generator is suspended again, and the
-   value of the :token:`expression_list` is returned to :meth:`next`'s caller.
+   with a :meth:`~generator.__next__` method, the current :keyword:`yield`
+   expression always evaluates to :const:`None`.  The execution then continues
+   to the next :keyword:`yield` expression, where the generator is suspended
+   again, and the value of the :token:`expression_list` is returned to
+   :meth:`next`'s caller.
    If the generator exits without yielding another value, a :exc:`StopIteration`
    exception is raised.
 
diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
index b4f09c2..3283e54 100644
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -737,11 +737,11 @@ using a :keyword:`for` statement::
 This style of access is clear, concise, and convenient.  The use of iterators
 pervades and unifies Python.  Behind the scenes, the :keyword:`for` statement
 calls :func:`iter` on the container object.  The function returns an iterator
-object that defines the method :meth:`__next__` which accesses elements in the
-container one at a time.  When there are no more elements, :meth:`__next__`
-raises a :exc:`StopIteration` exception which tells the :keyword:`for` loop to
-terminate.  You can call the :meth:`__next__` method using the :func:`next`
-built-in function; this example shows how it all works::
+object that defines the method :meth:`~iterator.__next__` which accesses
+elements in the container one at a time.  When there are no more elements,
+:meth:`__next__` raises a :exc:`StopIteration` exception which tells the
+:keyword:`for` loop to terminate.  You can call the :meth:`__next__` method
+using the :func:`next` built-in function; this example shows how it all works::
 
    >>> s = 'abc'
    >>> it = iter(s)
@@ -761,8 +761,8 @@ built-in function; this example shows how it all works::
 
 Having seen the mechanics behind the iterator protocol, it is easy to add
 iterator behavior to your classes.  Define an :meth:`__iter__` method which
-returns an object with a :meth:`__next__` method.  If the class defines
-:meth:`__next__`, then :meth:`__iter__` can just return ``self``::
+returns an object with a :meth:`~iterator.__next__` method.  If the class
+defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
 
    class Reverse:
        """Iterator for looping over a sequence backwards."""
@@ -819,8 +819,8 @@ easy to create::
 
 Anything that can be done with generators can also be done with class based
 iterators as described in the previous section.  What makes generators so
-compact is that the :meth:`__iter__` and :meth:`__next__` methods are created
-automatically.
+compact is that the :meth:`__iter__` and :meth:`~generator.__next__` methods
+are created automatically.
 
 Another key feature is that the local variables and execution state are
 automatically saved between calls.  This made the function easier to write and
diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst
index 762977c..7782663 100644
--- a/Doc/whatsnew/3.0.rst
+++ b/Doc/whatsnew/3.0.rst
@@ -771,7 +771,7 @@ Operators And Special Methods
   respectively).
 
 * :pep:`3114`: the standard :meth:`next` method has been renamed to
-  :meth:`__next__`.
+  :meth:`~iterator.__next__`.
 
 * The :meth:`__oct__` and :meth:`__hex__` special methods are removed
   -- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert
@@ -807,7 +807,7 @@ Builtins
   To get the old behavior of :func:`input`, use ``eval(input())``.
 
 * A new built-in function :func:`next` was added to call the
-  :meth:`__next__` method on an object.
+  :meth:`~iterator.__next__` method on an object.
 
 * The :func:`round` function rounding strategy and return type have
   changed.  Exact halfway cases are now rounded to the nearest even