Feel free to submit a patch to fix the docs.

Changing the API is not an option -- it's been like this since the
tp_iternext slot was added, and it's been designed like this for a
reason: so that in the common case of iterating over a built-in sequence
type no exception objects have to be created.  In particular the
for-loop code would just discard the StopIteration instance again.

The requirement that the exception is *optional* is so that if you're
calling a Python iterator that *does* create the exception, the
exception object (with whatever data the creator might have attached to
it) doesn't get lost (or worse, have to be recreated).

Calling PyIter_Next() here instead of inlining it would not be
advantageous; it would just slow things down since we'd have to make a
redundant call to PyErr_Occurred() to distinguish the StopIteration case
from other errors.