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

[Nick Coghlan]

On 29 December 2016 at 06:41, Steve Dower <steve.dower at python.org> wrote:

> 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.
>

Making it opt-in in the documentation could make the build validation
easier: check the list from the *docs* against the actual symbols being
exported by the headers.

That would have a few benefits:

- if you accidentally add a new function to the stable ABI, you get a test
failure
- if you deliberately add a new function to the stable ABI, but forget to
document it as such, you get a test failure
- if the stable ABI version added directive in the docs doesn't match the
stable ABI version used in the headers, you get a test failure

(That suggests the tests would need to check the headers with all stable
ABI versions from 3.2 up to the current release and ensure they match the
current C API documentation)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20161231/e59099b1/attachment.html>