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

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

-- 
Eric.