Added module map generation docs and some clean-up.

llvm-svn: 192792

clang-tools-extra/docs/ModularizeUsage.rst

@@ -1,5 +1,5 @@
 ================
-modularize Usage
+Modularize Usage
 ================
 
 ``modularize [<modularize-options>] <include-files-list> [<front-end-options>...]``
@@ -20,7 +20,7 @@ but must be on the same line. For example::
   header2.h
   header3.h: header1.h header2.h
 
-Note that unless a "-prefix (header path)" option is specified,
+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.
@@ -38,4 +38,14 @@ Modularize Command Line Options
 
   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.
+  directory.  Use ``-prefix`` to specify a different directory.
+
+.. option:: -module-map-path=<module-map-path>
+
+  Generate a module map and output it to the given file.  See the description
+  in :ref:`module-map-generation`.
+
+.. option:: -root-module=<root-name>
+
+  Put modules generated by the -module-map-path option in an enclosing
+  module with the given name.  See the description in :ref:`module-map-generation`.

clang-tools-extra/docs/modularize.rst

@@ -17,6 +17,11 @@ under different circumstances. These conditions cause modules built from the
 headers to behave poorly, and should be fixed before introducing a module
 map.
 
+:program:`modularize` also has an assistant mode option for generating
+a module map file based on the provided header list.  The generated file
+is a functional module map that can be used as a starting point for a
+module.map file.
+
 Getting Started
 ===============
 
@@ -101,3 +106,116 @@ and can produce error message like the following::
   extern "C" {
   ^
   The "extern "C" {}" block is here.
+
+.. _module-map-generation:
+
+Module Map Generation
+=====================
+
+If you specify the ``-module-map-path=<module map file>``,
+:program:`modularize` will output a module map based on the input header list.
+A module will be created for each header.  Also, if the header in the header
+list is a partial path, a nested module hierarchy will be created in which a
+module will be created for each subdirectory component in the header path,
+with the header itself represented by the innermost module.  If other headers
+use the same subdirectories, they will be enclosed in these same modules also.
+
+For example, for the header list::
+
+  SomeTypes.h
+  SomeDecls.h
+  SubModule1/Header1.h
+  SubModule1/Header2.h
+  SubModule2/Header3.h
+  SubModule2/Header4.h
+  SubModule2.h
+
+The following module map will be generated::
+
+  // Output/NoProblemsAssistant.txt
+  // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+       -root-module=Root NoProblemsAssistant.modularize
+  
+  module SomeTypes {
+    header "SomeTypes.h"
+    export *
+  }
+  module SomeDecls {
+    header "SomeDecls.h"
+    export *
+  }
+  module SubModule1 {
+    module Header1 {
+      header "SubModule1/Header1.h"
+      export *
+    }
+    module Header2 {
+      header "SubModule1/Header2.h"
+      export *
+    }
+  }
+  module SubModule2 {
+    module Header3 {
+      header "SubModule2/Header3.h"
+      export *
+    }
+    module Header4 {
+      header "SubModule2/Header4.h"
+      export *
+    }
+    header "SubModule2.h"
+    export *
+  }
+
+An optional ``-root-module=<root-name>`` option can be used to cause a root module
+to be created which encloses all the modules.
+
+For example, with the same header list from above::
+
+  // Output/NoProblemsAssistant.txt
+  // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \
+       -root-module=Root NoProblemsAssistant.modularize
+  
+  module Root {
+    module SomeTypes {
+      header "SomeTypes.h"
+      export *
+    }
+    module SomeDecls {
+      header "SomeDecls.h"
+      export *
+    }
+    module SubModule1 {
+      module Header1 {
+        header "SubModule1/Header1.h"
+        export *
+      }
+      module Header2 {
+        header "SubModule1/Header2.h"
+        export *
+      }
+    }
+    module SubModule2 {
+      module Header3 {
+        header "SubModule2/Header3.h"
+        export *
+      }
+      module Header4 {
+        header "SubModule2/Header4.h"
+        export *
+      }
+      header "SubModule2.h"
+      export *
+    }
+  }
+
+Note that headers with dependents will be ignored with a warning, as the
+Clang module mechanism doesn't support headers the rely on other headers
+to be included first.
+
+The module map format defines some keywords which can't be used in module
+names.  If a header has one of these names, an underscore ('_') will be
+prepended to the name.  For example, if the header name is ``header.h``,
+because ``header`` is a keyword, the module name will be ``_header``.
+For a list of the module map keywords, please see:
+`Lexical structure <http://clang.llvm.org/docs/Modules.html#lexical-structure>`_