[cfe-dev] [RFC] Removing libclang APIs to traverse the comment AST

[Dmitri Gribenko]

On Wed, Nov 13, 2013 at 9:16 AM, Philip Reames
<listmail at philipreames.com> wrote:
> On 11/12/13 5:50 PM, Dmitri Gribenko wrote:
>>
>> Hello,
>>
>> I'd like to remove libclang APIs to traverse the comment AST.
>> Instead, I would recommend to use clang_FullComment_getAsXML, which
>> provides the same information, but does not expose implementation
>> details of the comment AST.
>
> I am not currently a user of the comment API, but I object to the general
> direction you appear to be taking.  Maybe I've just been scarred by too many
> bad experiences with trying to parse badly thought out XML documents, but
> I'd *much* rather have a plain C API rather than an XML only one.

I hope that our comment XML API is well-designed.  We have a schema,
we have a lot of tests, and we verify that all our output conforms to
the schema.  Did you have a chance to take a look at the schema and
example output?  Please tell me what you think and if anything looks
wrong.

> Also, given that this is a public API which has been communicated to be
> fairly stable, I'm concerned by the fact that you appear to be removing
> large chunks.

Yes, this fact actually concerns me.  This is why I started this
discussion on the mailing list.

The original reason to provide these APIs was to implement a testing
mode for comments in c-index-test.  These APIs were not meant for
other uses, but I see that I failed to communicate that in the
documentation at all.

> Can you provide a concrete reason for wanting to remove these
> APIs?  What actual change is it blocking?

I think this is a separate issue, but here are some details.

I'll be sending an RFC for this change as well, because I think that
this is a major parsing *model* change.  It does not affect the
resulting output in normal cases, but will do what the user intended
in more unusual cases.

On the AST side, it boils down to changing BlockCommandComment to
contain multiple paragraphs inside, which will allow commands like
\param to have multi-paragraph descriptions.  On libclang side, this
change, for example, makes clang_BlockCommandComment_getParagraph()
return incomplete results -- just the first paragraph.

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>*/