[cfe-dev] [PATCH] Tooling docs - structuring proposal

[Manuel Klimek]

On Thu, Apr 19, 2012 at 6:43 PM, Anna Zaks <ganna at apple.com> wrote:
>
> "need to run over a specific subset of files in your project which is not
> necessarily related to any changes"
> It's unclear what you mean by "not necessarily related to any changes".

Done, hopefully.

On Fri, Apr 20, 2012 at 8:31 AM, David Röthlisberger <david at rothlis.net> wrote:
> On 19 Apr 2012, at 10:44, Manuel Klimek wrote:
>> Attached is a first version of Tooling.html for review.
>
> Hi Manuel!
>
> One thing missing from this overview is that after reading it I still don't really know what LibTooling offers. Is the only difference between LibTooling and LibClang that LibTooling is C++ not C, and that it gives full control over the Clang AST? If it offers other convenient functionality, it might be worth (very briefly) listing that functionality specifically (right here on this page, not LibTooling.html).

Plus the build system point, pretty much, yes... I've added a point
for sharing code with clang plugins.

> Is LibTooling less "high level" than LibClang? (I understand that it offers fuller access to the details of the Clang AST, so in a sense it is more "low level", but does that also mean that doing simple things is more difficult?)

LibClang offers more high level abstractions (I added that in the "Do
not use LibTooling..." list)

> Or with LibTooling are you essentially using the same Clang API (for the AST etc) as when you are writing a Plugin, but with additional helper functions provided by LibTooling?

Yep.

> Some minor points of style (these are only suggestions):
>
>> --- Tooling.html.orig
>> +++ Tooling.html
>> @@ -28,6 +28,8 @@
>>  </ul>
>>  <p>Use LibClang when you...</p>
>>  <ul>
>> +  <li>want to run tools over a single file, or a specific subset of files,
>> +  independently of the build system</li>
>>    <li>want to interface with clang from other languages than C++</li>
>>    <li>need a stable interface that takes care to be backwards compatible</li>
>>    <li>want powerful high-level abstractions, like iterating throught an AST
>> @@ -37,6 +39,7 @@
>>  <p>Do not use LibClang when you...</p>
>>  <ul>
>>    <li>want full control over the Clang AST</li>
>> +  <li>want to run as part of the build triggered by dependency changes</li>
>>  </ul>
>>
>>  <!-- ======================================================================= -->
>
> ...because I want to compare the 3 options against each other, so anything that holds for LibClang *and* LibTooling should be listed under both.

But ... those are exactly the *differences* :) I tried to put that in
positively formulated in the Clang Plugins section.

>> @@ -70,7 +72,7 @@
>>  <h2 id="libtooling"><a href="http://clang.llvm.org/doxygen/namespaceclang_1_1tooling.html">LibTooling</a></h2>
>>  <!-- ======================================================================= -->
>>
>> -<p>LibTooling is a library aimed at writing standalone tools, as well as
>> +<p>LibTooling is C++ interface aimed at writing standalone tools, as well as
>>  integrating into services that run clang tools.</p>
>>  <p>Canonical examples of when to use LibTooling:</p>
>>  <ul>
>
> ...to mirror the structure of the LibClang section, instead of leaving the reader to infer the C++ness of the interface from the "do not use" bullet-point later on.

Done.

>
>> @@ -86,7 +88,7 @@
>>  <p>Do not use LibTooling when you...</p>
>>  <ul>
>>    <li>want to run as part of the build triggered by dependency changes</li>
>> -  <li>want a stable high-level interface</li>
>> +  <li>want a stable interface</li>
>>    <li>do not want to write your tools in C++</li>
>>  </ul>
>
> ...this depends on the answer to my question "is LibTooling less high-level", but I think the stability of the interface is a separate concern from its high-levelness.

Done.

> Thanks for doing this! Sorry for nit-picking. :-)

If you think what you're doing is nit-picking, you have not been
subjected to nit-picking yet :)

Thanks for the review!

Cheers,
/Manuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120420/80df554e/attachment.html>