Consise doc on which C api calls do things with ref counts?

[Tom Culliton]

In article <8bc1qc$8ih at gap.cco.caltech.edu>,
Robert Kern <kern at caltech.edu> wrote:
>In article <uKeC4.1930$U95.30716 at news.pacbell.net>,
>	"Grant Munsey" <gmunsey at adobe.com> writes:
>> I though I saw mention of a concise doc that tells exactly what
>> each of the Python C api calls does with object refcounts.
>> Is there such a thing?

Not really IMO.

>> I just wanna make sure I don't decrement my refcount one too
>> many times and disappear!

Probably better than leaking, since you're likely to detect it
faster. ;-)

>The main C API Reference was just updated today to provide that 
>information.
>
>http://www.python.org/doc/api/api.html

It's a big improvement over what was there, but it could stand to be
even more explicit.  Not to mention that I really hate the "steals a
reference" idiom, which is just not intuitive to me.

I really want to see something like:

	does not modify ...			(read only, limited scope)
	makes a copy of ...
	increfs ...				(sharing)
	decrefs ...
	keeps a reference without increfing	(assumes ownership)
	returns a new ...			(factory/constructor)
	returns a copy of ...
	...

called out explicitly for every parameter and the return value,
especially since none of the function protoytpes use "const" to
indicate when a parameter is used but not changed in any way.

BTW - Why don't we use const?