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

[Brett Cannon]

On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <ronaldoussoren at mac.com> wrote:

>
> > On 27 Dec 2016, at 20:04, Serhiy Storchaka <storchaka at gmail.com> wrote:
> >
> > From the documentation:
> >
> > https://docs.python.org/3/c-api/stable.html
> >
> >    In the C API documentation, API elements that are not part of the
> limited API are marked as "Not part of the limited API."
> >
> > But they don't.
> >
> > I prepared a sample patch that adds the notes to Unicode Objects and
> Codecs C API (http://bugs.python.org/issue29086). I'm going to add them
> to all C API.
> >
> > What are your though about formatting the note? Should it be before the
> description, after the description, but before the "deprecated" directive
> (as in the patch), or after the first paragraph of the description? Should
> it be on the separate line or be appended at the end of the previous
> paragraph, or starts the first paragraph (if before the description)? May
> be introduce a special directive for it?
>
> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20161228/74957190/attachment.html>