[3.12] gh-121834: Improve complex C-API docs (GH-121835)

[sobolevn]

(cherry picked from commit 72dccd6)

Since PyComplex_RealAsDouble uses PyFloat_AsDouble, it can still fail there:

cpython/Objects/complexobject.c

Lines 258 to 267 in a15ed56

	double
	PyComplex_RealAsDouble(PyObject *op)
	{
	if (PyComplex_Check(op)) {
	return ((PyComplexObject *)op)->cval.real;
	}
	else {
	return PyFloat_AsDouble(op);
	}
	}

While PyComplex_ImagAsDouble is always successful:

cpython/Objects/complexobject.c

Lines 269 to 278 in a15ed56

	double
	PyComplex_ImagAsDouble(PyObject *op)
	{
	if (PyComplex_Check(op)) {
	return ((PyComplexObject *)op)->cval.imag;
	}
	else {
	return 0.0;
	}
	}

• Issue: Improve complex C-API error descriptions #121834

---

📚 Documentation preview 📚: https://cpython-previews--121897.org.readthedocs.build/

[sobolevn]

cc @skirpichev

[skirpichev]

One remark on PyComplex_ImagAsDouble(). The rest LGTM.