[Python-Dev] Support for marking limited API elements in C API docs

[Georg Brandl]

Am 12.10.2013 22:16, schrieb Antoine Pitrou:

>> >> Well, I may be reading PEP 384 wrongly, but the point is exactly to have a
>> >> *stable* API for *non-core* developers to rely upon, so that they can build
>> >> extensions that don't need to be recompiled for every version of Python.
>> > 
>> > This is true.
>> > 
>> > However, I find the proposed markup not very enlightening :-)
>> > I would prefer if "limited" APIs where marked with a :stableabi: tag.
>> 
>> The way I did it was based on the expected number of changes, which would
>> be lower with the "not-limited" elements being labeled.  But changing it
>> around is trivial.
> 
> Well, tagging things which are "not something" feels weird IMHO.

Sorry, that seems like arbitrary bike-shedding.  It's like saying you don't
want to document that pickle, shelve and marshal are not safe against
untrusted data, but rather document that all other modules are.

>> > ("limited API" is really a bad synonym for "stable ABI" IMO)
>> 
>> It's not a synonym: to get a stable ABI, you use the limited API.
> 
> I still don't like that name, because it doesn't convey any interesting
> information. "Stable ABI" is immediately informative.

It can be changed, but we document the C API, not an ABI.

cheers,
Georg