<div dir="ltr">Any fields that are just the values of a Clang enum can probably be documented by just linking to the appropriate clang doxygen (and specifying how the output corresponds to those names).<div><br></div><div>
-- Sean Silva</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Oct 31, 2013 at 8:38 PM, John Thompson <span dir="ltr"><<a href="mailto:John.Thompson.JTSoftware@gmail.com" target="_blank">John.Thompson.JTSoftware@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: jtsoftware<br>
Date: Thu Oct 31 19:38:04 2013<br>
New Revision: 193841<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=193841&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=193841&view=rev</a><br>
Log:<br>
pp-trace user documentation - beginnings<br>
<br>
Added:<br>
clang-tools-extra/trunk/docs/pp-trace.rst<br>
Modified:<br>
clang-tools-extra/trunk/docs/index.rst<br>
<br>
Modified: clang-tools-extra/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/index.rst?rev=193841&r1=193840&r2=193841&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/index.rst?rev=193841&r1=193840&r2=193841&view=diff</a><br>
==============================================================================<br>
--- clang-tools-extra/trunk/docs/index.rst (original)<br>
+++ clang-tools-extra/trunk/docs/index.rst Thu Oct 31 19:38:04 2013<br>
@@ -17,6 +17,7 @@ Contents<br>
<br>
clang-modernize<br>
modularize<br>
+ pp-trace<br>
<br>
<br>
Doxygen Documentation<br>
<br>
Added: clang-tools-extra/trunk/docs/pp-trace.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/pp-trace.rst?rev=193841&view=auto" target="_blank">http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/pp-trace.rst?rev=193841&view=auto</a><br>
==============================================================================<br>
--- clang-tools-extra/trunk/docs/pp-trace.rst (added)<br>
+++ clang-tools-extra/trunk/docs/pp-trace.rst Thu Oct 31 19:38:04 2013<br>
@@ -0,0 +1,169 @@<br>
+.. index:: pp-trace<br>
+<br>
+==================================<br>
+pp-trace User's Manual<br>
+==================================<br>
+<br>
+.. toctree::<br>
+ :hidden:<br>
+<br>
+:program:`pp-trace` is a standalone tool that traces preprocessor<br>
+activity. It's also used as a test of Clang's PPCallbacks interface.<br>
+It runs a given source file through the Clang preprocessor, displaying<br>
+selected information from callback functions overidden in a PPCallbacks<br>
+derivation. The output is in a high-level YAML format, described in<br>
+:ref:`OutputFormat`.<br>
+<br>
+.. _Usage:<br>
+<br>
+pp-trace Usage<br>
+==============<br>
+<br>
+Command Line Format<br>
+-------------------<br>
+<br>
+``pp-trace [<pp-trace-options>] <source-file> [<front-end-options>...]``<br>
+<br>
+``<pp-trace-options>`` is a place-holder for options<br>
+specific to pp-trace, which are described below in<br>
+`pp-trace Command Line Options`.<br>
+<br>
+``<source-file>`` specifies the source file to run through the preprocessor.<br>
+<br>
+``<front-end-options>`` is a place-holder for regular Clang<br>
+front-end arguments, which must follow the <source-file>.<br>
+<br>
+Command Line Options<br>
+--------------------<br>
+<br>
+.. option:: -ignore <callback-name-list><br>
+<br>
+ This option specifies a comma-seperated list of names of callbacks<br>
+ that shouldn't be traced. It can be used to eliminate unwanted<br>
+ trace output. The callback names are the name of the actual<br>
+ callback function names in the PPCallbacks class:<br>
+<br>
+ * FileChanged<br>
+ * FileSkipped<br>
+ * FileNotFound<br>
+ * InclusionDirective<br>
+ * moduleImport<br>
+ * EndOfMainFile<br>
+ * Ident<br>
+ * PragmaDirective<br>
+ * PragmaComment<br>
+ * PragmaDetectMismatch<br>
+ * PragmaDebug<br>
+ * PragmaMessage<br>
+ * PragmaDiagnosticPush<br>
+ * PragmaDiagnosticPop<br>
+ * PragmaDiagnostic<br>
+ * PragmaOpenCLExtension<br>
+ * PragmaWarning<br>
+ * PragmaWarningPush<br>
+ * PragmaWarningPop<br>
+ * MacroExpands<br>
+ * MacroDefined<br>
+ * MacroUndefined<br>
+ * Defined<br>
+ * SourceRangeSkipped<br>
+ * If<br>
+ * Elif<br>
+ * Ifdef<br>
+ * Ifndef<br>
+ * Else<br>
+ * Endif<br>
+<br>
+.. option:: -output <output-file><br>
+<br>
+ By default, pp-trace outputs the trace information to stdout. Use this<br>
+ option to output the trace information to a file.<br>
+<br>
+.. _OutputFormat:<br>
+<br>
+pp-trace Output Format<br>
+======================<br>
+<br>
+The pp-trace output is formatted as YAML. See <a href="http://yaml.org/" target="_blank">http://yaml.org/</a> for general<br>
+YAML information. It's arranged as a sequence of information about the<br>
+callback call, include the callback name and argument information, for<br>
+example:::<br>
+<br>
+ ---<br>
+ - Callback: Name<br>
+ Argument1: Value1<br>
+ Argument2: Value2<br>
+ (etc.)<br>
+ ...<br>
+<br>
+With real data:::<br>
+<br>
+ ---<br>
+ - Callback: FileChanged<br>
+ Loc: "c:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:1:1"<br>
+ Reason: EnterFile<br>
+ FileType: C_User<br>
+ PrevFID: (invalid)<br>
+ (etc.)<br>
+ - Callback: FileChanged<br>
+ Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:5:1"<br>
+ Reason: ExitFile<br>
+ FileType: C_User<br>
+ PrevFID: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/Input/Level1B.h"<br>
+ - Callback: EndOfMainFile<br>
+ ...<br>
+<br>
+In all but one case (MacroDirective) the "Argument" scalars have the same<br>
+name as the argument in the corresponding PPCallbacks callback function.<br>
+<br>
+Callback Details<br>
+----------------<br>
+<br>
+The following sections describe the output format for each callback.<br>
+<br>
+FileChanged Callback<br>
+^^^^^^^^^^^^^^^^^^^^<br>
+<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+| Argument Name | Argument Value Syntax | Clang C++ Type | Description |<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+| Loc | "(file):(line):(col)" | SourceLocation | Where in the file. |<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+| Reason | (EnterFile|ExitFile|SystemHeaderPragma|RenameFile) | PPCallbacks::FileChangeReason| Reason for change. |<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+| FileType | (C_User|C_System|C_ExternCSystem) | SrcMgr::CharacteristicKind | Include type. |<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+| PrevFID | ((file)|(invalid)) | FileID | Previous file, if any.|<br>
++----------------+-----------------------------------------------------+------------------------------+-----------------------+<br>
+<br>
+Example:::<br>
+<br>
+ - Callback: FileChanged<br>
+ Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:1:1"<br>
+ Reason: EnterFile<br>
+ FileType: C_User<br>
+ PrevFID: (invalid)<br>
+<br>
+(More callback documentation to come...)<br>
+<br>
+Building pp-trace<br>
+=================<br>
+<br>
+To build from source:<br>
+<br>
+1. Read `Getting Started with the LLVM System`_ and `Clang Tools<br>
+ Documentation`_ for information on getting sources for LLVM, Clang, and<br>
+ Clang Extra Tools.<br>
+<br>
+2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give<br>
+ directions for how to build. With sources all checked out into the<br>
+ right place the LLVM build will build Clang Extra Tools and their<br>
+ dependencies automatically.<br>
+<br>
+ * If using CMake, you can also use the ``pp-trace`` target to build<br>
+ just the pp-trace tool and its dependencies.<br>
+<br>
+.. _Getting Started with the LLVM System: <a href="http://llvm.org/docs/GettingStarted.html" target="_blank">http://llvm.org/docs/GettingStarted.html</a><br>
+.. _Building LLVM with CMake: <a href="http://llvm.org/docs/CMake.html" target="_blank">http://llvm.org/docs/CMake.html</a><br>
+.. _Clang Tools Documentation: <a href="http://clang.llvm.org/docs/ClangTools.html" target="_blank">http://clang.llvm.org/docs/ClangTools.html</a><br>
+<br>
<br>
<br>
_______________________________________________<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>
</blockquote></div><br></div>