commit 2972991969b6841b361085d8c0dd0b964ebfd04f
author Bruno Cardoso Lopes <bruno.cardoso@gmail.com> Fri Dec 22 02:53:30 2017 +0000
committer Bruno Cardoso Lopes <bruno.cardoso@gmail.com> Fri Dec 22 02:53:30 2017 +0000
tree 772acc3f7a74cae4e3732a2d5b0d62c7c1c7cfa5
parent 67885f5d582ade8fc8ba8569e41666b2aeb81b5c

[Modules] Change private modules rules and warnings

We used to advertise private modules to be declared as submodules
(Foo.Private). This has proven to not scale well since private headers
might carry several dependencies, introducing unwanted content into the
main module and often causing dep cycles.

Change the canonical way to name it to Foo_Private, forcing private
modules as top level ones, and provide warnings under -Wprivate-module
to suggest fixes for other private naming. Update documentation to
reflect that.

rdar://problem/31173501

llvm-svn: 321337

clang/docs/Modules.rst

diff --git a/clang/docs/Modules.rst b/clang/docs/Modules.rst
index 757be61..2fa38be 100644
--- a/clang/docs/Modules.rst
+++ b/clang/docs/Modules.rst
@@ -859,10 +859,12 @@
 
   module Foo {
     header "Foo.h"
-    
-    explicit module Private {
-      header "Foo_Private.h"
-    }
+    ...
+  }
+
+  module Foo_Private {
+    header "Foo_Private.h"
+    ...
   }
 
 
@@ -873,7 +875,7 @@
 
 Private module map files, which are named ``module.private.modulemap``
 (or, for backward compatibility, ``module_private.map``), allow one to
-augment the primary module map file with an additional submodule. For
+augment the primary module map file with an additional modules. For
 example, we would split the module map file above into two module map
 files:
 
@@ -883,9 +885,9 @@
   module Foo {
     header "Foo.h"
   }
-  
+
   /* module.private.modulemap */
-  explicit module Foo.Private {
+  module Foo_Private {
     header "Foo_Private.h"
   }
 
@@ -899,13 +901,12 @@
 
 When writing a private module as part of a *framework*, it's recommended that:
 
-* Headers for this module are present in the ``PrivateHeaders``
-  framework subdirectory.
-* The private module is defined as a *submodule* of the public framework (if
-  there's one), similar to how ``Foo.Private`` is defined in the example above.
-* The ``explicit`` keyword should be used to guarantee that its content will
-  only be available when the submodule itself is explicitly named (through a
-  ``@import`` for example).
+* Headers for this module are present in the ``PrivateHeaders`` framework
+  subdirectory.
+* The private module is defined as a *top level module* with the name of the
+  public framework prefixed, like ``Foo_Private`` above. Clang has extra logic
+  to work with this naming, using ``FooPrivate`` or ``Foo.Private`` (submodule)
+  trigger warnings and might not work as expected.
 
 Modularizing a Platform
 =======================