Diagnostics are typically read in monospace (and caret diagnostics don't make sense without monospace) so please use monospace for the example diagnostics. See <http://sphinx-doc.org/rest.html#source-code>.
If you haven't stumbled across it already, you may find < http://llvm.org/docs/SphinxQuickstartTemplate.html> useful. -- Sean Silva On Fri, Sep 20, 2013 at 10:40 AM, John Thompson < [email protected]> wrote: > Author: jtsoftware > Date: Fri Sep 20 09:40:52 2013 > New Revision: 191091 > > URL: http://llvm.org/viewvc/llvm-project?rev=191091&view=rev > Log: > Added modularize documentation. > > Added: > clang-tools-extra/trunk/docs/ModularizeUsage.rst > clang-tools-extra/trunk/docs/modularize.rst > Modified: > clang-tools-extra/trunk/docs/index.rst > > Added: clang-tools-extra/trunk/docs/ModularizeUsage.rst > URL: > http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/ModularizeUsage.rst?rev=191091&view=auto > > ============================================================================== > --- clang-tools-extra/trunk/docs/ModularizeUsage.rst (added) > +++ clang-tools-extra/trunk/docs/ModularizeUsage.rst Fri Sep 20 09:40:52 > 2013 > @@ -0,0 +1,41 @@ > +===================== > +modularize Usage > +===================== > + > +``modularize [<modularize-options>] <include-files-list> > [<front-end-options>...]`` > + > +``<modularize-options>`` is a place-holder for options > +specific to modularize, which are described below in > +`Modularize Command Line Options`. > + > +``<include-files-list>`` specifies the path of a file name for a > +file containing the newline-separated list of headers to check > +with respect to each other. Lines beginning with '#' and empty > +lines are ignored. Header file names followed by a colon and > +other space-separated file names will include those extra files > +as dependencies. The file names can be relative or full paths, > +but must be on the same line. For example: > + > + | header1.h > + | header2.h > + | header3.h: header1.h header2.h > + > +Note that unless a "-prefix (header path)" option is specified, > +non-absolute file paths in the header list file will be relative > +to the header list file directory. Use -prefix to specify a different > +directory. > + > +``<front-end-options>`` is a place-holder for regular Clang > +front-end arguments, which must follow the <include-files-list>. > +Note that by default, the underlying Clang front end assumes .h files > +contain C source, so you might need to specify the ``-x c++`` Clang option > +to tell Clang that the header contains C++ definitions. > + > +Modularize Command Line Options > +============================ > + > +.. option:: -prefix <header-path> > + > + Prepend the given path to non-absolute file paths in the header list > file. > + By default, headers are assumed to be relative to the header list file > + directory. Use -prefix to specify a different directory. > > Modified: clang-tools-extra/trunk/docs/index.rst > URL: > http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/index.rst?rev=191091&r1=191090&r2=191091&view=diff > > ============================================================================== > --- clang-tools-extra/trunk/docs/index.rst (original) > +++ clang-tools-extra/trunk/docs/index.rst Fri Sep 20 09:40:52 2013 > @@ -16,6 +16,7 @@ Contents > :maxdepth: 1 > > clang-modernize > + modularize > > > Doxygen Documentation > > Added: clang-tools-extra/trunk/docs/modularize.rst > URL: > http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/modularize.rst?rev=191091&view=auto > > ============================================================================== > --- clang-tools-extra/trunk/docs/modularize.rst (added) > +++ clang-tools-extra/trunk/docs/modularize.rst Fri Sep 20 09:40:52 2013 > @@ -0,0 +1,96 @@ > +.. index:: modularize > + > +================================== > +Modularize User's Manual > +================================== > + > +.. toctree:: > + :hidden: > + > + ModularizeUsage > + > +:program:`modularize` is a standalone tool that checks whether a set of > headers > +provides the consistent definitions required to use modules. For example, > it > +detects whether the same entity (say, a NULL macro or size_t typedef) is > +defined in multiple headers or whether a header produces different > definitions > +under different circumstances. These conditions cause modules built from > the > +headers to behave poorly, and should be fixed before introducing a module > +map. > + > +Getting Started > +=============== > + > +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 ``modularize`` target to build > + just the modularize tool and its dependencies. > + > +Before continuing, take a look at :doc:`ModularizeUsage` to see how to > invoke > +modularize. > + > +.. _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 > + > +What Modularize Checks > +====================== > + > +Modularize will do normal C/C++ parsing, reporting normal errors and > warnings, > +but will also report special error messages like the following: > + > + | error: '(symbol)' defined at multiple locations: > + | (file):(row):(column) > + | (file):(row):(column) > + > + error: header '(file)' has different contents depending on how it was > + included > + > +The latter might be followed by messages like the following: > + > + | note: '(symbol)' in (file) at (row):(column) not always provided > + > +Checks will also be performed for macro expansions, defined(macro) > +expressions, and preprocessor conditional directives that evaluate > +inconsistently, and can produce error messages like the following: > + > + | (...)/SubHeader.h:11:5: > + | #if SYMBOL == 1 > + | ^ > + | error: Macro instance 'SYMBOL' has different values in this header, > + | depending on how it was included. > + | 'SYMBOL' expanded to: '1' with respect to these inclusion paths: > + | (...)/Header1.h > + | (...)/SubHeader.h > + | (...)/SubHeader.h:3:9: > + | #define SYMBOL 1 > + | ^ > + | Macro defined here. > + | 'SYMBOL' expanded to: '2' with respect to these inclusion paths: > + | (...)/Header2.h > + | (...)/SubHeader.h > + | (...)/SubHeader.h:7:9: > + | #define SYMBOL 2 > + | ^ > + | Macro defined here. > + > +Checks will also be performed for '#include' directives that are > +nested inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks, > +and can produce error message like the following: > + > + | IncludeInExtern.h:2:3: > + | #include "Empty.h" > + | ^ > + | error: Include directive within extern "C" {}. > + | IncludeInExtern.h:1:1: > + | extern "C" { > + | ^ > + | The "extern "C" {}" block is here. > > > _______________________________________________ > 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
