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

[David Röthlisberger]

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).

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?)

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?

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.

> @@ -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.

> @@ -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.

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

Dave.