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