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

[Georg Brandl]

Am 12.10.2013 22:09, schrieb Eric V. Smith:
> On 10/12/2013 4:04 PM, Georg Brandl wrote:
>> Am 12.10.2013 21:56, schrieb 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.
>> 
>> The way I did it was based on the expected number of changes, which would
>> be lower with the "not-limited" elements being labeled.  But changing it
>> around is trivial.
> 
> I'm not sure I understand what's being labeled "notlimited". But it
> seems to be a tautology that the stable API/ABI is not changing. So I
> think it makes more sense to label those as "stableabi" and be finished
> with this task, rather than trying to remember to add some markup every
> time we add a new function.

This is true.  I've inverted the logic now.  Volunteers still welcome :)

Georg