Added module map generation docs and some clean-up.

llvm-svn: 192792

1 files changed, 118 insertions, 0 deletions

diff --git a/clang-tools-extra/docs/modularize.rst b/clang-tools-extra/docs/modularize.rst
index a389a7ab2b8..6e964dd337b 100644
--- a/clang-tools-extra/docs/modularize.rst
+++ b/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>`_