[Python-Dev] Extension doc bugs

[uche.ogbuji@fourthought.com]

I'm using the bleeding-edge documentation at 

http://python.sourceforge.net/devel-docs/api/api.html

I know that it's not complete until someone has the time to do so, but I've 
run into a few places where it's completely wrong.

For instance, from the object protocol docs: 

"""
int PyObject_Cmp (PyObject *o1, PyObject *o2, int *result) 
      Compare the values of o1 and o2 using a routine provided by o1, if one   
       exists, otherwise with a routine provided by o2. The result of the
      comparison is returned in result. Returns -1 on failure. This is the     
       equivalent of the Python statement "result = cmp(o1, o2)".
"""

After getting weird behavior implementing this, and then squinting at the 
relevant Python 2.0 code, it appears that in actuality the Cmp function is to 
return the direct comparison results (-1, 0, 1 based on ordering of the 
parameters)  furthermore, there is no such "result" argument.

4Suite has a lot of C extension code developed by squinting at Python sources 
and long gdb sessions and I have a feeling that in many cases we're taking up 
hacks that would get us into trouble across versions, and all that; but the 
"official" interfaces and behaviors are not documented (or only poorly 
documented).  In general, the C API docs are in a rather sorry state and 
though I doubt I could do a great deal about fixing it, I'd be interested in 
discussion of the matter, and perhaps making what contribution I can.

Is the doc-sig the best place for this?  My experience there wouldn't seem to 
encourage this conclusion (most of the discussion is of docstring syntax and 
neat-o automagic document generators).


-- 
Uche Ogbuji                               Principal Consultant
uche.ogbuji@fourthought.com               +1 303 583 9900 x 101
Fourthought, Inc.                         http://Fourthought.com 
4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA
Software-engineering, knowledge-management, XML, CORBA, Linux, Python