<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Nov 13, 2013 at 1:59 PM, Dmitri Gribenko <span dir="ltr"><<a href="mailto:gribozavr@gmail.com" target="_blank">gribozavr@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On Wed, Nov 13, 2013 at 9:16 AM, Philip Reames<br>
<<a href="mailto:listmail@philipreames.com">listmail@philipreames.com</a>> wrote:<br>
> On 11/12/13 5:50 PM, Dmitri Gribenko wrote:<br>
>><br>
>> Hello,<br>
>><br>
>> I'd like to remove libclang APIs to traverse the comment AST.<br>
>> Instead, I would recommend to use clang_FullComment_getAsXML, which<br>
>> provides the same information, but does not expose implementation<br>
>> details of the comment AST.<br>
><br>
> I am not currently a user of the comment API, but I object to the general<br>
> direction you appear to be taking. Maybe I've just been scarred by too many<br>
> bad experiences with trying to parse badly thought out XML documents, but<br>
> I'd *much* rather have a plain C API rather than an XML only one.<br>
<br>
</div>I hope that our comment XML API is well-designed. We have a schema,<br>
we have a lot of tests, and we verify that all our output conforms to<br>
the schema. Did you have a chance to take a look at the schema and<br>
example output? Please tell me what you think and if anything looks<br>
wrong.<br>
<div class="im"><br>
> Also, given that this is a public API which has been communicated to be<br>
> fairly stable, I'm concerned by the fact that you appear to be removing<br>
> large chunks.<br>
<br>
</div>Yes, this fact actually concerns me. This is why I started this<br>
discussion on the mailing list.<br>
<br>
The original reason to provide these APIs was to implement a testing<br>
mode for comments in c-index-test. These APIs were not meant for<br>
other uses, but I see that I failed to communicate that in the<br>
documentation at all.<br></blockquote><div><br></div><div>Why did you even put them in the header *and the exports list* if they aren't public API?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im"><br>
> Can you provide a concrete reason for wanting to remove these<br>
> APIs? What actual change is it blocking?<br>
<br>
</div>I think this is a separate issue, but here are some details.<br>
<br>
I'll be sending an RFC for this change as well, because I think that<br>
this is a major parsing *model* change. It does not affect the<br>
resulting output in normal cases, but will do what the user intended<br>
in more unusual cases.<br>
<br>
On the AST side, it boils down to changing BlockCommandComment to<br>
contain multiple paragraphs inside, which will allow commands like<br>
\param to have multi-paragraph descriptions. On libclang side, this<br>
change, for example, makes clang_BlockCommandComment_getParagraph()<br>
return incomplete results -- just the first paragraph.<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>-- Sean Silva</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im HOEnZb"><br>
Dmitri<br>
<br>
--<br>
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if<br>
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com">gribozavr@gmail.com</a>>*/<br>
</div><div class="HOEnZb"><div class="h5">_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
</div></div></blockquote></div><br></div></div>