r207392 - libclang: split out the documentation comment API

[Dmitri Gribenko]

On Mon, Apr 28, 2014 at 8:16 AM, Alp Toker <alp at nuanti.com> wrote:
>
> On 28/04/2014 07:22, Dmitri Gribenko wrote:
>>
>> On Mon, Apr 28, 2014 at 3:39 AM, Alp Toker <alp at nuanti.com> wrote:
>>>
>>> Author: alp
>>> Date: Sun Apr 27 21:39:27 2014
>>> New Revision: 207392
>>>
>>> URL: http://llvm.org/viewvc/llvm-project?rev=207392&view=rev
>>> Log:
>>> libclang: split out the documentation comment API
>>>
>>> It's possible that the "comment AST" may be replaced or split out in the
>>> midterm, any anyway this makes the headers easier to read.
>>>
>>> Developers don't currently need to include "clang-c/Documentation.h"
>>> explicitly
>>> and there's no macro to test for availability yet.
>>>
>>> The raw comment and brief comment accessors have been kept in Index.h
>>> though
>>> brief support may also move here as a separate proposal.
>>>
>>> This is not a deprecation, just a gentle separation of concerns as we
>>> look to
>>> simplify the built-in representation of comment nodes and support
>>> external
>>> comment processors.
>>
>> Alp,
>>
>> If you would like to "simplify" built-in representation of comment
>> nodes by replacing or splitting out a major part of implementation,
>> please discuss this first.  You have never replied to my other email,
>> where I said that it is unclear to me what your goals are, and without
>> understanding the goals it is impossible to review changes like that.
>
>
> Sure, it'll be discussed.
>
> The general approach for now is just to tidy the layering a little without
> changing functionality.
>
> The next ideas are to avoid global Comment.h inclusion from ASTContext.h and
> fix the layering of RawComment and FullComment. It's also perhaps worth
> splitting out the comment dumper from ASTDumper given that comments aren't
> strictly part of the AST but rather a separate document that makes
> references in.

This sounds reasonable.

> Some longer-term goals -- to improve -Wdocumentation performance (which has
> been discussed before), support code completion within comments and the
> checking of cross-references between translation units.

These are awesome goals as well.

> Most of all I'm certain that ~20,000 LoC can be reduced for what boils down
> to parsing a few comments and checking that param commands match the user's
> function parameters.

Given that I am the primary author of this code, I am skeptical of
such claims.  Doxygen is complicated, non-trivial to parse, and
non-uniform in its syntax and semantic rules.

> When the implementation starts to add HTML5 rules and JavaScript validators
> in libclang(!) while the basic one-liner comment parsing isn't yet
> dogfoodable due to performance issues it's worth taking a step back.
> Seriously, let's fix this.

Please don't conflate these issues.  HTML is an indivisible part of
Doxygen.  In fact, because of insufficient level of HTML semantic
analysis, Clang's implementation of comment parsing differs from
Doxygen (I can provide examples if required).

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