A couple of -1.0 error return codes aren't documented, see for
example PyFloat_AsDouble() and PyComplex_AsCComplex().

Well, it's sort of documented implicitly:  from

http://docs.python.org/c-api/intro.html#exceptions

"In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns an error indicator.  If not documented otherwise, this indicator is either NULL or -1, depending on the function’s return type."

Good point. - I just had to figure out if the pattern

    Py_complex c = PyComplex_AsCComplex(w);
    if (c.real == -1.0 && PyErr_Occurred()) {
        ...

will always be reliable in the future. The source of PyComplex_AsCComplex()
suggests that it will, on the other hand in getargs.c the pattern isn't
used.

The passage you quoted is quite clear, so I wouldn't mind if you
close this.

I'm not sure how many people read that passage though. :)

I think it's still a good idea to spell it out explicitly in each function description. The document pointed by Mark is long enough that it's easy to overlook or forget that single important statement.

Hi,

Here is the patch I propose for this issue. This is my first attempt to contribute to Python, so please don't hit me too hard if I did something wrong. :)

When browsing the source code of complexobject.c, I also noticed that the return values of the _Py_c_quot and _Py_c_pow (which return zero in case of error) weren't documented at 

http://docs.python.org/dev/c-api/complex.html#_Py_c_quot

There's a typo in the patch: it's PyErr_Occurred (two r's), not PyErr_Occured.
Otherwise, looks good to me.

I fixed the typo and the markup.

New changeset 68cbf6551710 by Antoine Pitrou in branch '3.2':
Issue #13522: document error return values of some float and complex C API functions.
http://hg.python.org/cpython/rev/68cbf6551710

New changeset 1f096611baf4 by Antoine Pitrou in branch 'default':
Issue #13522: document error return values of some float and complex C API functions.
http://hg.python.org/cpython/rev/1f096611baf4

New changeset 059e4d752fbe by Antoine Pitrou in branch '2.7':
Issue #13522: document error return values of some float and complex C API functions.
http://hg.python.org/cpython/rev/059e4d752fbe

Committed now. Thank you for the patch!

_Py_c_pow() doc is wrong:

+   If :attr:`exp.imag` is not null, or :attr:`exp.real` is negative,
+   this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.

The function only fails if num=0 and exp.real < 0 or if num=0 and exp.imag != 0.

Fixed.

Previous patch was also wrong, sorry!

New changeset 67a4e8fe650e by Victor Stinner in branch 'default':
Issue #13522: Fix _Py_co_pow() documentation
http://hg.python.org/cpython/rev/67a4e8fe650e

New changeset edc981ce8748 by Victor Stinner in branch '3.2':
Issue #13522: Fix _Py_co_pow() documentation
http://hg.python.org/cpython/rev/edc981ce8748

New changeset 2863470caebb by Victor Stinner in branch '2.7':
Issue #13522: Fix _Py_co_pow() documentation
http://hg.python.org/cpython/rev/2863470caebb