Adds a introductionary document to the Clang AST.

Next steps are adding information about types & source location handling.

git-svn-id: 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/IntroductionToTheClangAST.html b/docs/IntroductionToTheClangAST.html
new file mode 100644
index 0000000..28175dd
--- /dev/null
+++ b/docs/IntroductionToTheClangAST.html
@@ -0,0 +1,139 @@
+          "">
+<title>Introduction to the Clang AST</title>
+<link type="text/css" rel="stylesheet" href="../menu.css" />
+<link type="text/css" rel="stylesheet" href="../content.css" />
+<!--#include virtual="../menu.html.incl"-->
+<div id="content">
+<h1>Introduction to the Clang AST</h1>
+<p>This document gives a gentle introduction to the mysteries of the Clang AST.
+It is targeted at developers who either want to contribute to Clang, or use
+tools that work based on Clang's AST, like the AST matchers.</p>
+<!-- FIXME: Add link once we have an AST matcher document -->
+<!-- ======================================================================= -->
+<h2 id="intro">Introduction</h2>
+<!-- ======================================================================= -->
+<p>Clang's AST is different from ASTs produced by some other compilers in that it closely
+resembles both the written C++ code and the C++ standard. For example,
+parenthesis expressions and compile time constants are available in an unreduced
+form in the AST. This makes Clang's AST a good fit for refactoring tools.</p>
+<p>Documentation for all Clang AST nodes is available via the generated
+<a href="">Doxygen</a>. The doxygen online
+documentation is also indexed by your favorite search engine, which will make
+a search for clang and the AST node's class name usually turn up the doxygen
+of the class you're looking for (for example, search for: clang ParenExpr).</p>
+<!-- ======================================================================= -->
+<h2 id="examine">Examining the AST</h2>
+<!-- ======================================================================= -->
+<p>A good way to familarize yourself with the Clang AST is to actually look
+at it on some simple example code. Clang has a builtin AST-dump modes, which
+can be enabled with the flags -ast-dump and -ast-dump-xml. Note that -ast-dump-xml
+currently only works with debug-builds of clang.</p>
+<p>Let's look at a simple example AST:</p>
+# cat
+int f(int x) {
+  int result = (x / 42);
+  return result;
+# Clang by default is a frontend for many tools; -cc1 tells it to directly
+# use the C++ compiler mode. -undef leaves out some internal declarations.
+$ clang -cc1 -undef -ast-dump-xml
+... cutting out internal declarations of clang ...
+&lt;TranslationUnit ptr="0x4871160">
+ &lt;Function ptr="0x48a5800" name="f" prototype="true">
+  &lt;FunctionProtoType ptr="0x4871de0" canonical="0x4871de0">
+   &lt;BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+   &lt;parameters>
+    &lt;BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+   &lt;/parameters>
+  &lt;/FunctionProtoType>
+  &lt;ParmVar ptr="0x4871d80" name="x" initstyle="c">
+   &lt;BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+  &lt;/ParmVar>
+  &lt;Stmt>
+(CompoundStmt 0x48a5a38 &lt;, line:4:1>
+  (DeclStmt 0x48a59c0 &lt;line:2:3, col:24>
+    0x48a58c0 "int result =
+      (ParenExpr 0x48a59a0 &lt;col:16, col:23> 'int'
+        (BinaryOperator 0x48a5978 &lt;col:17, col:21> 'int' '/'
+          (ImplicitCastExpr 0x48a5960 &lt;col:17> 'int' &lt;LValueToRValue>
+            (DeclRefExpr 0x48a5918 &lt;col:17> 'int' lvalue ParmVar 0x4871d80 'x' 'int'))
+          (IntegerLiteral 0x48a5940 &lt;col:21> 'int' 42)))")
+  (ReturnStmt 0x48a5a18 &lt;line:3:3, col:10>
+    (ImplicitCastExpr 0x48a5a00 &lt;col:10> 'int' &lt;LValueToRValue>
+      (DeclRefExpr 0x48a59d8 &lt;col:10> 'int' lvalue Var 0x48a58c0 'result' 'int'))))
+  &lt;/Stmt>
+ &lt;/Function>
+<p>In general, -ast-dump-xml dumps declarations in an XML-style format and
+statements in an S-expression-style format.
+The toplevel declaration in a translation unit is always the
+<a href="">translation unit declaration</a>.
+In this example, our first user written declaration is the
+<a href="">function declaration</a>
+of 'f'. The body of 'f' is a <a href="">compound statement</a>,
+whose child nodes are a <a href="">declaration statement</a>
+that declares our result variable, and the
+<a href="">return statement</a>.</p>
+<!-- ======================================================================= -->
+<h2 id="context">AST Context</h2>
+<!-- ======================================================================= -->
+<p>All information about the AST for a translation unit is bundled up in the class
+<a href="">ASTContext</a>.
+It allows traversal of the whole translation unit starting from
+<a href="">getTranslationUnitDecl</a>,
+or to access Clang's <a href="">table of identifiers</a>
+for the parsed translation unit.</p>
+<!-- ======================================================================= -->
+<h2 id="nodes">AST Nodes</h2>
+<!-- ======================================================================= -->
+<p>Clang's AST nodes are modeled on a class hierarchy that does not have a common
+ancestor. Instead, there are multiple larger hierarchies for basic node types like
+<a href="">Decl</a> and
+<a href="">Stmt</a>. Many
+important AST nodes derive from <a href="">Type</a>,
+<a href="">Decl</a>,
+<a href="">DeclContext</a> or
+<a href="">Stmt</a>,
+with some classes deriving from both Decl and DeclContext.</p>
+<p>There are also a multitude of nodes in the AST that are not part of a
+larger hierarchy, and are only reachable from specific other nodes,
+like <a href="">CXXBaseSpecifier</a>.
+<p>Thus, to traverse the full AST, one starts from the <a href="">TranslationUnitDecl</a>
+and then recursively traverses everything that can be reached from that node
+- this information has to be encoded for each specific node type. This algorithm
+is encoded in the <a href="">RecursiveASTVisitor</a>.
+See the <a href="">RecursiveASTVisitor tutorial</a>.</p>
+<p>The two most basic nodes in the Clang AST are statements (<a href="">Stmt</a>)
+and declarations (<a href="">Decl</a>).
+Note that expressions (<a href="">Expr</a>)
+are also statements in Clang's AST.</p>