I've moved out common behavior and data for all command-line tools to a separate class (CommandLineClangTool.cpp), added more help, added one integration test for clang-ast-dump, added links to the recently added tooling setup how to. This should address most of the issues. I've decided to put off large-scale documentation efforts for now and first see how it goes in practical sense.<div class="gmail_extra">
<br><br><div class="gmail_quote">On Thu, Jul 12, 2012 at 9:57 PM, Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+//===- examples/Tooling/ClangCheck.cpp - Clang check tool<br>
-----------------===//<br>
<br>
The file header is still the "ClangCheck" one.<br>
<br>
+//  This file implements a clang-ast-dump tool that dumps specified parts<br>
+//  of an AST of a number of translation units.<br>
<br>
This header comment is rather uninformative (as are many others in the<br>
clang codebase, unfortunately).<br>
<br>
It gives me a bit of a taste of what the tool does, but leaves me<br>
hanging. The parts that I think "leave me hanging" are:<br>
<br>
"dumps *specified* parts" (emphasis mine): how do I specify them? what<br>
things are matchable? can I use a regex? can I use the new ASTMatcher<br>
library (although IIRC the dynamic matchers are not merged yet, so the<br>
answer here is no)?<br>
<br>
"of a number of translation units": how do I specify them? do I need<br>
some kind of special setup? if so, how so I set it up?<br>
<br>
As a person interested in using this tool, and maybe hacking on it, I<br>
would like to at least see:<br>
<br>
* A high level description of the tool. As in all writing, remember<br>
your audience: they have already seen the filename, so they can<br>
already guess that it is related to "dumping ASTs"; thus a "high level<br>
description" is going to be one level lower than "it dumps ASTs".<br>
* Expected use cases and why this tool is needed (e.g. comparison with<br>
`clang -ast-dump`)<br>
* Quickstart. If a nontrivial setup is required, provide pointers to<br>
the relevant documentation.<br>
* Future directions you envision. One can only provide useful insight<br>
into future directions after grokking the tool; hence the original<br>
author is usually the best person to enunciate them. This usually<br>
provides insight into the context which brought the tool into<br>
existence and gives future hackers leads on where to continue.<br>
<br>
Thanks for the cool tool,<br>
--Sean Silva<br>
<div><div class="h5"><br>
On Thu, Jul 12, 2012 at 10:27 AM, Alexander Kornienko <<a href="mailto:alexfh@google.com">alexfh@google.com</a>> wrote:<br>
> Hi,<br>
><br>
> This patch adds the clang-ast-dump tool based on the Clang Tooling<br>
> infrastructure. It can help users of AST matchers to explore and understand<br>
> AST by selectively dumping it. This is a first version aimed at collecting<br>
> feedback and feature requests.<br>
><br>
> --<br>
> Regards,<br>
> Alexander<br>
><br>
</div></div>> _______________________________________________<br>
> cfe-commits mailing list<br>
> <a href="mailto:cfe-commits@cs.uiuc.edu">cfe-commits@cs.uiuc.edu</a><br>
> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div><div><font color="#666666"><span style="border-top-width:2px;border-right-width:0px;border-bottom-width:0px;border-left-width:0px;border-top-style:solid;border-right-style:solid;border-bottom-style:solid;border-left-style:solid;border-top-color:rgb(213,15,37);border-right-color:rgb(213,15,37);border-bottom-color:rgb(213,15,37);border-left-color:rgb(213,15,37);padding-top:2px;margin-top:2px">Alexander Kornienko |</span><span style="border-top-width:2px;border-right-width:0px;border-bottom-width:0px;border-left-width:0px;border-top-style:solid;border-right-style:solid;border-bottom-style:solid;border-left-style:solid;border-top-color:rgb(51,105,232);border-right-color:rgb(51,105,232);border-bottom-color:rgb(51,105,232);border-left-color:rgb(51,105,232);padding-top:2px;margin-top:2px"> Software Engineer |</span></font><span style="border-top-width:2px;border-right-width:0px;border-bottom-width:0px;border-left-width:0px;border-top-style:solid;border-right-style:solid;border-bottom-style:solid;border-left-style:solid;border-top-color:rgb(0,153,57);border-right-color:rgb(0,153,57);border-bottom-color:rgb(0,153,57);border-left-color:rgb(0,153,57);padding-top:2px;margin-top:2px"><font color="#666666"> </font><a href="mailto:alexfh@google.com" style="color:rgb(17,85,204)" target="_blank">alexfh@google.com</a> |</span><span style="border-top-width:2px;border-right-width:0px;border-bottom-width:0px;border-left-width:0px;border-top-style:solid;border-right-style:solid;border-bottom-style:solid;border-left-style:solid;border-top-color:rgb(238,178,17);border-right-color:rgb(238,178,17);border-bottom-color:rgb(238,178,17);border-left-color:rgb(238,178,17);padding-top:2px;margin-top:2px"> <a value="+35315435283" style="color:rgb(17,85,204)">+49 151 221 77 957</a></span></div>
</div><div><font color="#666666"><span style="background-color:rgb(255,255,255);font-family:Arial,Verdana,sans-serif">Google Germany GmbH | </span><span style="background-color:rgb(255,255,255);font-family:Arial,Verdana,sans-serif">Dienerstr. 12 | </span><span style="background-color:rgb(255,255,255);font-family:Arial,Verdana,sans-serif">80331 München</span></font></div>
<br>
</div>