r207392 - libclang: split out the documentation comment API

[Alp Toker]

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.

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.

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.

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.

Alp.

-- 
http://www.nuanti.com
the browser experts