On Tue, 27 Dec 2016 at 12:15 Ronald Oussoren <ronaldousso...@mac.com> wrote:
> > > On 27 Dec 2016, at 20:04, Serhiy Storchaka <storch...@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.
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
