From: Eli Friedman <eli.friedman@gmail.com>
Date: Mon, 18 May 2009 01:16:21 +0000 (+0000)
Subject: Add some comments to ASTConsumers.h describing what the different
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=18d868f067cd49e6bb25380f5edc9ca9f761fbf9;p=clang

Add some comments to ASTConsumers.h describing what the different
ASTConsumers actually do.



git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@71992 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/tools/clang-cc/ASTConsumers.h b/tools/clang-cc/ASTConsumers.h
index 4a1de11476..f270f36342 100644
--- a/tools/clang-cc/ASTConsumers.h
+++ b/tools/clang-cc/ASTConsumers.h
@@ -32,24 +32,42 @@ class PreprocessorFactory;
 struct CompileOptions;
 class LangOptions;
 
+// AST pretty-printer: prints out the AST in a format that is close to the
+// original C code.  The output is intended to be in a format such that
+// clang could re-parse the output back into the same AST, but the
+// implementation is still incomplete.
 ASTConsumer *CreateASTPrinter(llvm::raw_ostream* OS = NULL);
 
+// AST dumper: dumps the raw AST in human-readable form to stderr; this is
+// intended for debugging. A normal dump is done with FullDump = false;
+// with FullDump = true, the dumper waits until the end of the translation
+// unit to dump the AST.
 ASTConsumer *CreateASTDumper(bool FullDump);
 
+// Graphical AST viewer: for each function definition, creates a graph of
+// the AST and displays it with the graph viewer "dotty".  Also outputs
+// function declarations to stderr.
 ASTConsumer *CreateASTViewer();
 
+// DeclContext printer: prints out the DeclContext tree in human-readable form
+// to stderr; this is intended for debugging.
 ASTConsumer *CreateDeclContextPrinter();
 
+// ObjC rewriter: attempts tp rewrite ObjC constructs into pure C code.
+// This is considered experimental, and only works with Apple's ObjC runtime.
 ASTConsumer *CreateCodeRewriterTest(const std::string& InFile,
                                     const std::string& OutFile,
                                     Diagnostic &Diags,
                                     const LangOptions &LOpts);
-  
+
+// LLVM code generator: uses the code generation backend to generate LLVM
+// assembly. This runs optimizations depending on the CompileOptions
+// parameter. The output depends on the Action parameter.
 enum BackendAction {
-  Backend_EmitAssembly,
-  Backend_EmitBC,
-  Backend_EmitLL,
-  Backend_EmitNothing
+  Backend_EmitAssembly,  // Emit native assembly
+  Backend_EmitBC,        // Emit LLVM bitcode file
+  Backend_EmitLL,        // Emit human-readable LLVM assembly
+  Backend_EmitNothing    // Don't emit anything (benchmarking mode)
 };
 ASTConsumer *CreateBackendConsumer(BackendAction Action,
                                    Diagnostic &Diags,
@@ -58,19 +76,30 @@ ASTConsumer *CreateBackendConsumer(BackendAction Action,
                                    const std::string &InFile,
                                    const std::string &OutFile);
 
+// HTML printer: uses the rewriter to convert source code to HTML with
+// syntax highlighting suitable for viewing in a web-browser.
 ASTConsumer* CreateHTMLPrinter(const std::string &OutFile, Diagnostic &D,
                                Preprocessor *PP, PreprocessorFactory *PPF);
 
+// PCH generator: generates a precompiled header file; this file can be
+// used later with the PCHReader (clang-cc option -include-pch)
+// to speed up compile times.
 ASTConsumer *CreatePCHGenerator(const Preprocessor &PP,
                                 const std::string &OutFile);
 
+// Block rewriter: rewrites code using the Apple blocks extension to pure
+// C code.
 ASTConsumer *CreateBlockRewriter(const std::string &InFile,
                                  const std::string &OutFile,
                                  Diagnostic &Diags,
                                  const LangOptions &LangOpts);
-  
+
+// Inheritance viewer: for C++ code, creates a graph of the inheritance
+// tree for the given class and displays it with "dotty".
 ASTConsumer *CreateInheritanceViewer(const std::string& clsname);
 
+// Analyzer: runs various code analysis passes.  (The exact analyses
+// run is controlled by command-line options.)
 ASTConsumer* CreateAnalysisConsumer(Diagnostic &diags, Preprocessor *pp,
                                     PreprocessorFactory *ppf,
                                     const LangOptions &lopts,