From: Bruno Cardoso Lopes <bruno.cardoso@gmail.com>
Date: Thu, 16 Mar 2017 23:18:55 +0000 (+0000)
Subject: [Modules] Add documentation on private frameworks
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6113c885c45be5c67f665a06983b1b8e021d53e2;p=clang

[Modules] Add documentation on private frameworks

Expand a bit on private modules with some guidance on how to write
them in the context of frameworks.

rdar://problem/24758771

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@298012 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/Modules.rst b/docs/Modules.rst
index 141d3b8575..2b1bde2fed 100644
--- a/docs/Modules.rst
+++ b/docs/Modules.rst
@@ -360,6 +360,7 @@ The ``framework`` qualifier specifies that this module corresponds to a Darwin-s
   Name.framework/
     Modules/module.modulemap  Module map for the framework
     Headers/                  Subdirectory containing framework headers
+    PrivateHeaders/           Subdirectory containing framework private headers
     Frameworks/               Subdirectory containing embedded frameworks
     Resources/                Subdirectory containing additional resources
     Name                      Symbolic link to the shared library for the framework
@@ -842,6 +843,16 @@ would be available when ``Foo_Private.h`` is available, making it
 easier to split a library's public and private APIs along header
 boundaries.
 
+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).
+
 Modularizing a Platform
 =======================
 To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).