Added modularize documentation.

llvm-svn: 191091

clang-tools-extra/docs/ModularizeUsage.rst

@@ -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.

clang-tools-extra/docs/index.rst

@@ -16,6 +16,7 @@ Contents
    :maxdepth: 1
 
    clang-modernize
+   modularize
 
 
 Doxygen Documentation

clang-tools-extra/docs/modularize.rst

@@ -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.