[Python-Dev] Document C API that is not part of the limited API
steve.dower at python.org
Wed Dec 28 15:41:05 EST 2016
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.
More information about the Python-Dev