<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Nov 13, 2013 at 8:08 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 4:51 PM, Sean Silva <<a href="mailto:silvas@purdue.edu">silvas@purdue.edu</a>> wrote:<br>
><br>
> On Wed, Nov 13, 2013 at 1:59 PM, Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com">gribozavr@gmail.com</a>><br>
> wrote:<br>
</div><div class="im">>> 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>
><br>
> Why did you even put them in the header *and the exports list* if they<br>
> aren't public API?<br>
<br>
</div>As I said, not communicating this is my fault. I just added these<br>
APIs the same way as we usually add APIs to libclang.<br>
<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>
>> 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>
><br>
> It seems like all they can do is get the text of the paragraph, so why not<br>
> just fake up a dummy paragraph whose text content is the content of all the<br>
> paragraphs? and document this restriction and point the user to a new API<br>
> that gives the full access to the paragraphs? I'm also really worried that<br>
> this will also change the XML schema in an incompatible way: the XML schema<br>
> is by extension part of the stability promise of the C API, and can't be<br>
> changed incompatibly without breaking users.<br>
<br>
</div>Or we could only return the first paragraph. Faking a paragraph<br>
requires creating AST nodes, which requires memory allocation on the<br>
ASTContext, which is permanent.<br></blockquote><div><br></div><div>Why not create it on demand in "freeable" storage?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
The schema change is:<br>
<br>
Index: bindings/xml/comment-xml-schema.rng<br>
===================================================================<br>
--- bindings/xml/comment-xml-schema.rng»(revision 194522)<br>
+++ bindings/xml/comment-xml-schema.rng»(working copy)<br>
@@ -393,7 +393,9 @@<br>
<!-- In general, template parameters with whitespace discussion<br>
should not be emitted. Schema might be more strict here. --><br>
<element name="Discussion"><br>
- <ref name="TextBlockContent" /><br>
+ <oneOrMore><br>
+ <ref name="TextBlockContent" /><br>
+ </oneOrMore><br>
</element><br>
</element><br>
</oneOrMore><br>
@@ -435,7 +437,9 @@<br>
should not be emitted, unless direction is explicitly specified.<br>
Schema might be more strict here. --><br>
<element name="Discussion"><br>
- <ref name="TextBlockContent" /><br>
+ <oneOrMore><br>
+ <ref name="TextBlockContent" /><br>
+ </oneOrMore><br>
</element><br>
</element><br>
</oneOrMore><br>
<br>
I think that this change is compatible (but it depends on how one<br>
defines "compatible"). Previously, <Discussion> tag could contain<br>
only a single paragraph; after this change it can contain multiple.<br></blockquote><div><br></div><div>I'm not an XML expert, but that looks like it should be compatible for most non-pathological use cases.</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="HOEnZb"><div class="h5"><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></blockquote></div><br></div></div>