[Python-Dev] Support for marking limited API elements in C API docs

[Antoine Pitrou]

On Sat, 12 Oct 2013 21:19:16 +0200
Georg Brandl <g.brandl at gmx.net> wrote:
> Am 12.10.2013 20:20, schrieb Serhiy Storchaka:
> > 12.10.13 21:04, Georg Brandl написав(ла):
> >> in light of the recent thread about PEPs not forming part of the docs,
> >> I've just pushed a change that allows to document C API elements
> >> not part of the limited API as such.  It is done like this:
> >>
> >> ... c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
> >>     :notlimited:
> >>
> >> I have not yet begun adding these to the documents; if someone wants to
> >> help with this I am glad for volunteers.
> > 
> > Why this is needed? The limited API is unstable and only developers of 
> > CPython can use it (but they can look in headers).
> 
> Well, I may be reading PEP 384 wrongly, but the point is exactly to have a
> *stable* API for *non-core* developers to rely upon, so that they can build
> extensions that don't need to be recompiled for every version of Python.

This is true.

However, I find the proposed markup not very enlightening :-)
I would prefer if "limited" APIs where marked with a :stableabi: tag.

("limited API" is really a bad synonym for "stable ABI" IMO)

Regards

Antoine.