Please review patch to add '\headerfile' command conversion to HTML

[jahanian]

On Jan 31, 2013, at 11:31 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> Hi Fariborz,
> 
> On Thu, Jan 31, 2013 at 9:01 PM, jahanian <fjahanian at apple.com> wrote:
>> [Comment parsing]. Currently, comment parser does not recognize \headerfile, so merges its text to the following text.
>> This patch recognizes \headerfile command and, according to our requirement, places its text into
>> a separate <Para>…</Para> tag. Note that this is not a complete implementation of \headerfile
>> command. Our immediate need is to provide separate paragraph for its text and not mix it with the \brief text which follows it.
>> Please review.
> 
> 
> // expected-warning at +2 ...
> /// \headerfile ""
> /// \headerfile foo.h
> int test_duplicate_headerfile1(int);
> 
> We do want a warning here, right?

Yes. Test will be added for this warning.

> 
> +// CHECK-NEXT:           (CXComment_Text Text=[ Device.h ])
> +// CHECK-NEXT:           (CXComment_Text Text=[<Foundation])
> +// CHECK-NEXT:           (CXComment_Text Text=[/Device.h>])))
> 
> Nice that our HTML parser is forgiving enough not to recognize this as
> plain text...  Please also add tests for:
> 
> \headerfile <stdio.h>
> \headerfile <algorithm>
> 
>     Result << "<Abstract>";
> +    if (Parts.Headerfile)
> +      visit(Parts.Headerfile);
> 
> I don't think it is good to stuff this into the brief description.  It
> actually contradicts with your goal:
> 
>> Our immediate need is to provide separate paragraph for its text and not mix it with the \brief text which follows it.
> 
> Brief description should be short, and should start with something
> immediately helpful.  I think we should introduce a new tag, like
> <Headerfile>.  It looks like a good idea, since we already have
> <Declaration>.  Please put it before <Declaration> in the schema.

The idea was to add the header in a <Para> tag before the brief text. <Headerfile> tag is good idea. I need to talk to
our consumer client and make sure that they will agree to this.

- - Thanks for quick review, Fariborz

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