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

[Sean Silva]

On Wed, Nov 13, 2013 at 1:59 PM, Dmitri Gribenko <gribozavr at gmail.com>wrote:

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

Why did you even put them in the header *and the exports list* if they
aren't public API?


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

It seems like all they can do is get the text of the paragraph, so why not
just fake up a dummy paragraph whose text content is the content of all the
paragraphs? and document this restriction and point the user to a new API
that gives the full access to the paragraphs? I'm also really worried that
this will also change the XML schema in an incompatible way: the XML schema
is by extension part of the stability promise of the C API, and can't be
changed incompatibly without breaking users.

-- Sean Silva


>
> 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>*/
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20131113/19276a1b/attachment.html>