#2727: clarify tp_iternext docs.

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index e89ecf70fa607e4882756ed870edd833eac7613e..1807c92b5eedaa4c3c367a8cf96ca8ffc461095b 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -753,11 +753,12 @@ set.
 
 .. cmember:: iternextfunc PyTypeObject.tp_iternext
 
-   An optional pointer to a function that returns the next item in an iterator, or
-   raises :exc:`StopIteration` when the iterator is exhausted.  Its presence
-   normally signals that the instances of this type are iterators (although classic
-   instances always have this function, even if they don't define a :meth:`next`
-   method).
+   An optional pointer to a function that returns the next item in an iterator.
+   When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
+   exception may or may not be set.  When another error occurs, it must return
+   *NULL* too.  Its presence normally signals that the instances of this type
+   are iterators (although classic instances always have this function, even if
+   they don't define a :meth:`next` method).
 
    Iterator types should also define the :attr:`tp_iter` function, and that
    function should return the iterator instance itself (not a new iterator