[PATCH] LibTooling docs

Please find a first version attached.

The next step is a short intro on how to write a FrontendAction, which
is common to clang plugins and libtooling, and thus I thought I'd put
it into a separate doc.

Cheers,
/Manuel

LibTooling.html (7.01 KB)

LGTM!

-- Marshall

Marshall Clow Idio Software <mailto:mclow.lists@gmail.com>

A.D. 1517: Martin Luther nails his 95 Theses to the church door and is promptly moderated down to (-1, Flamebait).
        -- Yu Suzuki

Hi Manuel,

At the end of the document you specify that a compile_commands.json is created. I thought that Json has been abandonned as a format ?

– Matthieu

Nope, it hasn't. JSON is a full subset of YAML - the only thing that
changed is that we use the YAML parser to parse JSON.

Cheers,
/Manuel

Please find a first version attached.

The next step is a short intro on how to write a FrontendAction, which
is common to clang plugins and libtooling, and thus I thought I'd put
it into a separate doc.

Comments inline

Cheers,
Erik.

LibTooling

LibTooling is a library to support writing standalone tools based on Clang. This document will provide a basic walkthrough of how to write a tool using LibTooling.

Introduction

Tools built with LibTooling, like Clang Plugins, run FrontendActions over code. In this tutorial, we'll demonstrate the different ways of

Don't use "we". "This tutorial demonstrates ..." is better. Same for constructs like "we'll": in colloquial communication that is okay, but otherwise you should use "we will". The only kind-of-exception is "don't" or any use of "n't" for "not".

I disagree with the idea that we need to be overly formal in those
tutorials. Now, if you think that some of my bad grammar makes the
sentences hard to understand / read, I'm happy to change, but I don't
think that a style that's more dry makes it easier to read...

running clang's SyntaxOnlyAction, which basically runs a quick syntax check, over a bunch of code.

Try not to use "basically", as it might sound like you just don't know what really happens. Now in all honesty, I have no better way of phrasing this sentence...

Done (just removed the "basically" :slight_smile:

Parsing a code snippet in memory...

Ellipsis? Why not a dot/full-stop like in other headers?

Done.

If you ever wanted to run a FrontendAction over some sample code, for example to unit test parts of the Clang AST, runToolOnCode is what you looked for. Let me give you an example:

#include "clang/Tooling/Tooling.h"

TEST(runToolOnCode, CanSyntaxCheckCode) {
// runToolOnCode returns whether the action was correctly run over the
// given code.
EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
}

Writing a standalone tool.

Once you unit tested your FrontendAction to the point where it cannot possibly break, it's time to create a standalone tool. For a

"it is"

standalone tool to run clang, it first needs to figure out what command line arguments it needs for a specified file. To that end we want to create a CompilationDatabase.

".. we want to ..." could be read as one-of-the-ways-to-do-it. Is it? Otherwise just state: "To that end a CompilationDatabase is needed."

I try to avoid passive voice wherever possible. Changed to "To that
end we create a CompilationDatabase."

Creating a compilation database.

CompilationDatabase provides static factory functions to help with parsing compile commands from a build directory or the command line. To allow both explicit specification of a compile command line, as well as retrieving the compile command lines from a database, we can write:

"To allow....can write:" -> "The following code allows for both explicit specification of a compile command line, as well as retrieving the compile commands lines from a database."

Done.

int main(int argc, const char **argv) {
// First, try to create a fixed compile command database from the command line
// arguments.
llvm::OwningPtr<CompilationDatabase> Compilations(
FixedCompilationDatabase::loadFromCommandLine(argc, argv));

// Next, use normal llvm command line parsing to get the tool specific
// parameters.
cl::ParseCommandLineOptions(argc, argv);

if (!Compilations) {
// In case the user did not specify the compile command line via positional
// command line arguments after "--", try to load the compile commands from
// a database in the specified build directory.
std::string ErrorMessage;
Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
ErrorMessage));

// If there is still no valid compile command database, we don&#39;t know how
// to run the tool\.
if \(\!Compilations\)
  llvm::report\_fatal\_error\(ErrorMessage\);

}
...
}

Creating and running a ClangTool.

One we have a CompilationDatabase, we can create a ClangTool and run our FrontendAction over some code. For example, to run the

OnCe (note the C :slight_smile: ). But better: "Once the CompilationDatabase is created, ...."

Again, my strong preference for active voice trumps the idea of more formality.

SyntaxOnlyAction over the files "a.cc" and "b.cc" one would write:

"... one would write:" -> "the following code-snippet can be used:"

// A clang tool can run over a number of sources in the same process...
std::vector<std::string> Sources;
Sources.push_back("a.cc");
Sources.push_back("b.cc");

// We hand the CompilationDatabase we created and the sources to run over into
// the tool constructor.
ClangTool Tool(*Compilations, Sources);

// The ClangTool needs a new FrontendAction for each translation unit we run
// on. Thus, it takes a FrontendActionFactory as parameter. To create a
// FrontendActionFactory from a given FrontendAction type, we call
// newFrontendActionFactory<clang::SyntaxOnlyAction>().
int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());

Putting it together - the first tool.

Now we combine the two previous steps into our first real tool. This example tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.

"To combine the two..."

Not sure where this would go?

#include "llvm/Support/CommandLine.h"
#include "clang/Frontend/FrontendActions.h"
#include "clang/Tooling/CompilationDatabase.h"
#include "clang/Tooling/Tooling.h"

using namespace clang::tooling;
using namespace llvm;

cl::opt<std::string> BuildPath(
cl::Positional,
cl::desc("<build-path>"));

cl::list<std::string> SourcePaths(
cl::Positional,
cl::desc("<source0> [... <sourceN>]"),
cl::OneOrMore);

int main(int argc, const char **argv) {
llvm::OwningPtr<CompilationDatabase> Compilations(
FixedCompilationDatabase::loadFromCommandLine(argc, argv));
cl::ParseCommandLineOptions(argc, argv);
if (!Compilations) {
std::string ErrorMessage;
Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
ErrorMessage));
if (!Compilations)
llvm::report_fatal_error(ErrorMessage);
}
ClangTool Tool(*Compilations, SourcePaths);
return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
}

Running the tool on some code.

When you check out and build clang, clang-check is already built and available to you in bin/clang-check inside your build directory.

You can run try clang-check on a file in the llvm repository by specifying all the needed parameters after a "--" separator:

$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check . tools/clang/tools/clang-check/ClangCheck.cpp -- \
clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
-Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c

As an alternative, you can also configure cmake to output a compile command database into its build directory:

# Alternatively to calling cmake, use ccmake, toggle to advanced mode and
# set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .

This creates a file called compile_commands.json in the build directory. Now you can run clang-check over files in the project by specifying the build path as first argument and some source files as further positional arguments:

$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check $BD tools/clang/tools/clang-check/ClangCheck.cpp

Thanks for the review!

/Manuel

LibTooling.html (7 KB)

> But better: "Once the CompilationDatabase
> is created, ...."

Again, my strong preference for active voice trumps the idea of more
formality.

If I could chime in here, I want to suggest that the passive is
sometimes better, depending on the focus. (If you want to spend an
afternoon reading about the relatively recent, and strictly American,
indictment of the passive, I'd be happy to provide references.)

One reason the passive is adopted is to disguise agency. It leads to
lazy constructions. The K-12 writer is taught not to use the passive in
part because the formation permits not saying what he doesn't know.
"Rome was invaded in 256 AD."

In the earlier example:

"To that end we create a CompilationDatabase."

the agent matters: "we" set about creating the database over the course
of the next ~5 paragraphs. ("is needed" might be better if it
continued to explain by what or for what, if that mattered.)

When that's done,

> Once the CompilationDatabase is created,

agency is uninteresting, and "we" don't matter anymore. We're off to
the next thing.

Subject is topic: what matters isn't that we created the database
(aren't we great?) but that the database has been created (yay!).

I disagree with the idea that we need to be overly formal in those
tutorials. Now, if you think that some of my bad grammar makes the
sentences hard to understand / read, I'm happy to change

Quite. Pedantic rules will not great writing make.

Style manuals disagree on the use of contractions. Let us look forward
to the day when the best way to improve our documentation is to choose
between "can't" and "cannot".

--jkl

I re-read Chris' tutorials, and they are all active. So ignore that. :slight_smile: All your changes look fine!

Off the record: I am also a non-native English speaker (as I assume you are, correct me if I am wrong), but I learned that apparently "basically" is abused so much that some people will question if you really know what you are talking about :-/ And unfortunately, in my experience, I am afraid they are right. I do not doubt you knowledge, but it is something I had to learn "the hard way".

-- Erik

I re-read Chris' tutorials, and they are all active. So ignore that. :slight_smile: All your changes look fine!

Off the record: I am also a non-native English speaker (as I assume you are, correct me if I am wrong), but I learned that apparently "basically" is abused so much that some people will question if you really know what you are talking about :-/ And unfortunately, in my experience, I am afraid they are right. I do not doubt you knowledge, but it is something I had to learn "the hard way".

Yea, the basically was basically crap :slight_smile: I'm also non-native, so I'm
always happy to get different opinions :slight_smile:

Sometimes you have this "err... Oops moment when your son manages to hit the send-button on your touch device when you are checking the to/cc of a list... :-/

-- Erik

The following may be more work and overhead than you had in mind, but here goes:

I am a big fan of *testable* documentation. The easiest way is to generate the documentation from real code (like ClangCheck.cpp or unit tests) that is tested as part of your routine build. Your documentation stays in sync with changes to the code, and the examples in the documentation are guaranteed to work.

Doxygen isn't enough here; I've thrown up a simple proof of concept, inspired by Go's "codewalk" style of documentation, at https://github.com/drothlis/clang-libtooling-docs

https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html.src#L113
shows a code snippet taken directly from ClangCheck.cpp.
We would need to write additional tests from which to source the remaining code snippets in the document.

https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html.src#L123
shows a shell command in the documentation that is actually tested as part of the document-generation process.

This highlighted an error in the shell command! See the generated output:
https://github.com/drothlis/clang-libtooling-docs/blob/master/LibTooling.html#L149

Some thoughts on making this work on a large project:

a. The document generation should be run as part of every normal "make all" compilation.

b. The generated document should be checked into source control so that if someone changes ClangCheck.cpp they notice the effect on the documentation in their diffs. I suppose this can get tricky with out-of-source builds -- I'm confident it's doable with gmake but I have no experience with cmake.

c. The document-generation script won't work on Windows unless you have a cygwin-style shell, sed, perl, etc. so maybe the makefile needs to detect when to disable document generation.

Thoughts?
--Dave.

b. The generated document should be checked into source control so
that if someone changes ClangCheck.cpp they notice the effect on the
documentation in their diffs.

I see where you're going, but that's not the way. The changes might
not be meaningful to the documentation, and check-in time is not
*necesarily* the best time to update it. (I could argue the best time
is before the code is changed, for example, or that documentation is
best handled by someone better acquainted with English.)

You want to know that a given piece of code is documented somewhere,
because changes might invalidate the documentation. That is the
information you need to keep!

To verify that source and document match, it is enough to know
the filename, line numbers (or function name), and revision of quoted
source in the documentation. It could be embedded in the document or in
separate file. With a bit of sed(1) the quoted lines can be compared
to *any* other revision in the repository, at any time.

That said, having read and written some documentation, I'm
skeptical of how useful such a system would be. Documentation is
not "testable" because

1. not that much compilable code finds its way into the documentation,
and
2. in 2012 semantics cannot be asserted, much less verified.

After all all, documentation is mostly about how to use something, be
it a class, function, or utility. Restating the implementation isn't
useful or desirable. But, yes, examples need to be checked somehow.

a. The document generation should be run as part of every normal
"make all" compilation.

For every release there are many compilations. Why burden each one
with extraneous concerns? No mechanical means can verify that the
document is correct or even meaningful. Therefore the process of
making it correct falls to humans, just as testing and release
engineering do.

Good documentation can't be forced or enforced. It's the
product of conscientious work, nothing more and nothing less.

--jkl

Hi James,

I'm a little confused by some of your statements, not necessarily
disagreeing (because I'm not sure I understand them - and in some
cases it sounds like you don't understand (my understanding of)
David's either - but again, perhaps I'm just misreading) so I have a
few questions.

Manuel - sorry if this takes a bit of a tangent from your review... I
don't think any of this is likely to be sufficiently
relevant/important to require you to respond before committing your
documentation.

b. The generated document should be checked into source control so
that if someone changes ClangCheck.cpp they notice the effect on the
documentation in their diffs.

I see where you're going, but that's not the way. The changes might
not be meaningful to the documentation, and check-in time is not
*necesarily* the best time to update it.

Judging this particular piece of documentation - it includes a
character for character copy of code checked in & building in the
Clang source tree. What scenario would exist where there would be any
desire for this code to diverge, let alone in a way where the
divergence led to the documentation version becoming invalid?

(I could argue the best time
is before the code is changed, for example, or that documentation is
best handled by someone better acquainted with English.)

Possibly - though writing up at least an outline of the changes might
not be such a bad thing & further edits/tidy-up could be applied
later. Though in the case of "building" documentation, of course the
only thing that would really fail the build is the compilation failure
- so all we're talking about is correcting the same code to be correct
at all times. In both cases the surrounding documentation may still
become incorrect & need to be fixed at some point.

Though, like doxygen, I think having the documentation closer to the
sample wouldn't be a bad thing - it at least increases the
chances/opportunity of updating the documentation when you have the
best 'state' in mind to describe the changes you're making.

You want to know that a given piece of code is documented somewhere,
because changes might invalidate the documentation. That is the
information you need to keep!

To verify that source and document match, it is enough to know
the filename, line numbers (or function name), and revision of quoted
source in the documentation. It could be embedded in the document or in
separate file. With a bit of sed(1) the quoted lines can be compared
to *any* other revision in the repository, at any time.

I'm not sure quite what you're suggesting here - why would comparing
the (checked in) documentation to arbitrary revisions be helpful?

Clang documentation (even the live docs on the website for all of
LLVM) are generated in commit hooks - they're generally intended to be
kept totally in sync with the development work that is occurring.
Perhaps you're thinking of a more formal product release cycle
approach where large changes are made, planned, perhaps documentation
is written ahead of time (I'm not sure this happens very often -
usually even in a more waterfall-like model, it happens later rather
than earlier) & then the API is changed to match.

LLVM's development is a bit more fluid and incremental than that -
people experiment with different APIs, pieces change over time to fit
use cases better, etc.

That said, having read and written some documentation, I'm
skeptical of how useful such a system would be. Documentation is
not "testable" because

1. not that much compilable code finds its way into the documentation,

In this particular case, more than half this (rather short) document
is code samples. And half of the sample is a verbatim copy of an
actual building/running source file.

and
2. in 2012 semantics cannot be asserted, much less verified.

There's no reason the source code can't have test cases. Indeed test
cases are a great way of providing concrete examples to users & some
are even shown in this documentation page - "run this command & stuff
happens" (granted it would have to be sured up a little bit to turn
those examples into actually running test cases in the Clang build,
but I don't think it'd be a very large step & I'm not sure what kind
of in-tree testing clang-check has at the moment).

After all all, documentation is mostly about how to use something, be
it a class, function, or utility. Restating the implementation isn't
useful or desirable. But, yes, examples need to be checked somehow.

I'm not sure how any of this is "restating the implementation" - in
this case the code samples are use cases of the API being documented.
Test cases of those use cases then demonstrate what those use cases
mean. (perhaps the test cases could be written more directly in terms
of the API, but the API is designed for writing applications so I
don't think it's unreasonable to show it in that setting & then test
the resulting application)

a. The document generation should be run as part of every normal
"make all" compilation.

For every release there are many compilations. Why burden each one
with extraneous concerns?

Because we already are? The code in question is already part of the
build. The tests probably should be if they aren't already.

No mechanical means can verify that the
document is correct or even meaningful.

They can verify that parts of the document are correct - the samples.

Therefore the process of
making it correct falls to humans, just as testing and release
engineering do.

Testing doesn't always fall to humans - ideally as much of it as we
can falls to machines - we write the test cases, but we don't manually
do the testing all the time, just like we don't have to manually
verify the source code of samples every time.

Good documentation can't be forced or enforced. It's the
product of conscientious work, nothing more and nothing less.

I don't think David's suggestion magically enforces good
documentation, but it helps humans focus on the areas that machines
can't (currently) help with. It's akin to having a spellchecker in the
build system - just because your spelling is correct doesn't mean the
documentation is good - but if you're spelling isn't correct it should
probably be fixed (just like your example code). Indeed that's even
the same with production code itself and compiler warnings - good
warnings are a sign of bad code, but the absence of warnings doesn't
tell you the code is bug free. That's not an excuse to throw out the
diagnostics entirely.

- David

Hi James,

Hi David,

I appreciate the time you took to address what I was saying.

I may have misunderstood your post. I thought your were suggesting a
general purpose tool and a general policy. I'm not sure I want to
comment on one particular document. I have my reservations about it,
but I don't want (my version of) the perfect be the enemy of the good.

I also don't want to discourage the writing of documentation. As a
newcomer, I'm suffering from the dearth of documentation!

If my ideas appeal to you, maybe they can save you some work. If not,
well, the guy doing the work always gets priority over the guy
kibbitzing.

Judging this particular piece of documentation - it includes a
character for character copy of code checked in & building in the
Clang source tree. What scenario would exist where there would be any
desire for this code to diverge, let alone in a way where the
divergence led to the documentation version becoming invalid?

I wouldn't necessarily copy the code, and I wouldn't try to make every
code snippet compilable in situ. Why not? To let the documentation
omit lines unimportant to the point being made.

For example, the place to document which header files are needed is in
the reference manual. In a document of any size, #include directives
and error-handling code become a distraction from the main event.

Similarly, the comments in the code can't serve two masters. In
particular, tutorial comments are distracting and tiresome. In-line
comments are best kept minimal; the code should speak for itself.
Comments should be used to draw attention to some important aspect,
perhaps an assumption about state or preconditions.

(I realize not everyone agrees with these ideas. There's nothing that
*can* be said on the subject that would meet with universal agreement.
But I can point you to programmers we both admire who say the same
thing.)

How, then, to bring the code into the document, if not by copying it?
And how to verify it's right? Scripts, naturally. sed to extract the
lines from the code, and make(1) to merge them into the document
template, merge them into a compilable template, and compile the
result.

The scripts aren't free, of course. But neither is copying and pasting
the code whenever it's updated.

In both cases the surrounding documentation may still
become incorrect & need to be fixed at some point.

Yes. I think the problem of the English prose surrounding
the quoted code becoming outdated and thereby misleading is a far bigger
problem than that the quoted code will stop compiling.

Though, like doxygen, I think having the documentation closer to the
sample wouldn't be a bad thing - it at least increases the
chances/opportunity of updating the documentation

So they say. Having done both, and having met up with a lot of awful
doxygen output (as I bet you have, too), I'd say the evidence is
against. Unix has a long and successful history of putting the man
pages in the same directory as the source code.

I don't quite understand the theory that documentation doesn't get
written unless you rub the programmer's nose in it. People who don't
like to do it don't, no matter what form it takes. People who do
will.

> _With a bit of sed(1) the quoted
> lines can be compared to *any* other revision in the repository, at
> any time.

(Something in the ML software seems to be replacing "extra"
spaces with underscores. Would you happen to know if that's considered
a feature?)

why would comparing
the (checked in) documentation to arbitrary revisions be helpful?

To see if it's correct now, fsvo "now". To see if the documentation
from the last release still holds for the RC we just branched, for
example.

Documentation is correct as of version N. Code continues to version
N+1, N+2, ... N+n. At some point, document and code diverge. You
are saying that it must be fixed right then and there. I'm saying that
to work effeciently often means that the documentation and code are out
of synch for a little while.

Clang documentation (even the live docs on the website for all of
LLVM) are generated in commit hooks - they're generally intended to be
kept totally in sync with the development work that is occurring.

Clang just released 3.1. Perhaps today all its documentation is in
tip-top shape with every commit. That's great! In general, releases
involve a whole set of related changes, some deprecated ideas and some
new ones. With time, experience shows what's confusing and what didn't
work well. As the number of documents grows, so too does their
potential to contradict each other.

For these reasons I suggest documentation review is indeed
part of preparing a release, and that editing (and maintaining
something of single voice) is harder than making sure the
code samples they contain still compile.

But I accept some of this is cultural. I watched the release happen,
and I didn't notice anyone say, "Doc review!"

Perhaps you're thinking of a more formal product release cycle

I've never been paid to manage a release cycle or to write
official documentation. I've just found in my own work that
pre-release tends to be the time to scrutinize the docs.

And, yes, I agree documentation is normally written in arrears. That's
probably just as well. Clausewitz said, "The best plan does not
survive first contact with the enemy."

There's no reason the source code can't have test cases.

...

Testing doesn't always fall to humans

Sure, granted. I was thinking more about how failures get rectified.

> Good documentation can't be forced or enforced. _It's the
> product of conscientious work, nothing more and nothing less.

I don't think David's suggestion magically enforces good
documentation, but it helps humans focus on the areas that machines
can't (currently) help with.

That depends on where you think the humans need help focussing. For
me, coding and documentation are two loosely coupled processes
requiring different parts of the brain. At time of commit -- and
definitely for any compilation -- I'm most concerned with things
technical. Just because I've added a new parameter to a function
doesn't mean I have to touch up the documentation right now, or that I
can, or that I can do it well because it's 2:00 AM and I'm relieved
just to have checked in the code.

Seeing them as loosely coupled naturally leads in the direction of
"trust but verify": a system that both tolerates out-of-date
documentation and can track what needs to be updated.

But don't let me stand in your way (not that you were about to). As I
said at the outset, I offer my perspective only to try to save you
from going down what I see as a blind alley. I was a once a doxygen
fan, and I'm as big a fanatic of automating drudgery as you'll find.
The problem is, there are no shortcuts. The real "test" of
documentation, we agree, is in its usability, in what it communicates.
Automation doesn't have much to offer to that end beyond the routine
work of lacing it together.

Regards,

--jkl

Absolutely -- In fact I'm a bit sorry for distracting from the review of the documentation *content* by submitting my wacky ideas. Let's get Manuel's static html --which is really valuable work-- committed before carrying this discussion any further.

--David Röthlisberger.

Fwiw, when it comes to a kind of "code walkthrough", I think that something
like this <http://documentcloud.github.com/underscore/docs/underscore.html>
could be a good model. The docs are generated from comments *in the code*,
so that they are unlikely to go out of date. The program that does that
transformation is called Docco and it is very few lines of code (see here <
http://jashkenas.github.com/docco/>). There are ports of this tool for many
languages (they are listed on that page) and they are all equally small.

--Sean Silva

So, I've pondered this a bit over the weekend...

There are multiple things around this on my mind:
1. documentation is more than a code walkthrough - the documentation
must be able to be structured differently from the code, whose
structuring is imposed by a compiler (that's mainly as a direct answer
to Sean's proposal)
2. I like the idea of having testable code-snippets included in the
docs; the biggest problem is that I don't think it makes sense to have
a special solution for the docs I'm writing; we should take this
proposal to llvm-dev and discuss it with the people who're working on
doc standards for llvm already, like the proposed move towards a
different markup system altogether; the biggest problem here is people
willing to maintain it and convert existing docs - some of the ideas
around documentation have apparently been "in the works" for many
months now, but have always been too low prio
3. I also agree to some point with James' comments: documentation is a
people problem, which we cannot solve with technical means - and
having auto-checked syntax in documentation might disincentivice
engineers (like myself) from checking the docs; that said, as long as
the writers of the documentation think a system can help them, I think
we can use it - it's not like this will magically solve the problem of
too little documentation, but making documentation easier to maintain
is definitely something I'm interested in.

To me, my main concern seems to be (1). I don't want a special
solution for the docs around tooling.

David, why not bring up the whole question about automatically checked
documentation, and the documentation strategy in general (and your
ideas, obviously) up on llvm-dev?

Cheers,
/Manuel

Manuel Klimek wrote:

<h3 id="running">Running the tool on some code.</h3>
<p>When you check out and build clang, clang-check is already built and
available to you in bin/clang-check inside your build directory.</p>
<p>You can run try clang-check on a file in the llvm repository by

"You can try running"

Manuel Klimek wrote:

<h3 id="running">Running the tool on some code.</h3>
<p>When you check out and build clang, clang-check is already built and
available to you in bin/clang-check inside your build directory.</p>
<p>You can run try clang-check on a file in the llvm repository by

"You can try running"

Done & checked in.

Cheers,
/Manuel