[Python-Dev] Document C API that is not part of the limited API

[Steve Dower]

On 28Dec2016 1145, Brett Cannon wrote:
> On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <ronaldoussoren at mac.com
> <mailto:ronaldoussoren at mac.com>> wrote:
>     A directive would make it easier to ensure that the text about the
>     stable API is consistent.  I’d also consider adding that directive
>     to all API’s that *are* part of the stable API instead of the other
>     way around (that would also require changes to …/stable.html). That
>     would have two advantages: firstly it makes it easier to document
>     from which version an API is part of the stable ABI, and secondly
>     forgetting the annotation would imply that an API is not part of the
>     stable ABI instead of accidentally claiming to increase the stable ABI.
>
>
> I like Ronald's suggestion of both using a directive and making it for
> the stable ABI since it should be an opt-in thing for the API to be
> stable instead of opt-out.

The directive is a good idea, but I'm a little concerned about the 
stable API being opt-out in the headers and opt-in in the documentation.

Perhaps we should also figure out the preprocessor gymnastics we need to 
make it opt-in in the headers too? Though once we get the build 
validation to detect when the stable API changes accidentally it'll be 
less of an issue.

Cheers,
Steve