[cfe-commits] [PATCH] Add Python bindings to comment AST introspection APIs

[Dmitri Gribenko]

On Fri, Dec 21, 2012 at 3:13 AM, Gregory Szorc <gregory.szorc at gmail.com> wrote:
> On 12/20/12 5:01 PM, Dmitri Gribenko wrote:
>>
>> On Fri, Dec 21, 2012 at 2:58 AM, Gregory Szorc <gregory.szorc at gmail.com>
>> wrote:
>>>
>>> On 12/20/12 4:37 PM, Douglas Gregor wrote:
>>>>
>>>> I'm fine with removing the comment AST traversal routines. The XML is
>>>> far
>>>> better for clients.
>>>>
>>> XML is arguably a decent interchange format. But, I'd much prefer a more
>>> native and low-level API like we have today. I think it's terrific that
>>> comment XML is available. But, I think it is silly to force the incurred
>>> the
>>> cost for serialization and deserialization just to pass data through
>>> libclang.
>>>
>>> If you want to refactor the comment API so it isn't traversal based, I
>>> say
>>> go for it. But please don't force libclang consumers to use XML.
>>
>> What should happen to these APIs when the comment AST on the C++ side
>> of Clang changes?
>
>
> What should happen to the XML when the comment AST on the C++ side of Clang
> changes?

The issue is the binary-compatibility of libclang.so -- it will be
broken in case we decide to change AST traversal APIs, but the
getAsXML will stay the same no matter how XML changes.

> We're going to have API compatibility issues one way or another I think.
> Perhaps the right thing to do is clearly mark all comment APIs "experimental
> - use at your own risk" until things have stabilized?

As for any complex system, I don't think we can ever say "yes, this is
finished" about this.

> Also, going back to the root of this thread - it sounds like the comment API
> will soon change. As much as I would like to see the Python bindings gain
> this feature, perhaps its best to hold off on landing until things have
> stabilized?

I did not mean to say that I'm going to change that soon (because I
don't have a lot of time to do that now), but it will certainly change
when someone decides to add a new feature.  Just about any new feature
I can imagine will require a change in the AST:
* if we parse declaration references in \c, then inline command will
have more than just plain text as its argument.  (Maybe we can work
around this issue by allowing only a single link for \c, that will
span the whole source range of the argument)
* PR14335: allow \param foo,bar -- a single \param command will have
more than one parameter name. (We could work around this too, by
exposing only the first parameter name through the old API, and by
adding new enumeration APIs that will allow to see all parameters)

So certainly, workarounds are possible, and we can somehow maintain
the old API *and* keep binary compatibility.  But is it worth it?  It
depends on how useful it is.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/