[clang] [Doc] [C++20] [Modules] Clarify the reachability of internal partition units (PR #102572)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 updated https://github.com/llvm/llvm-project/pull/102572

>From c5766b29042cd5109c22f7c399ebc33ffd0f6b3b Mon Sep 17 00:00:00 2001
From: Chuanqi Xu <yedeng.yd at linux.alibaba.com>
Date: Fri, 9 Aug 2024 13:48:35 +0800
Subject: [PATCH 1/3] [Doc] [C++20] [Modules] Clarify the reachability of
 internal partition units

---
 clang/docs/StandardCPlusPlusModules.rst | 51 +++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 2478a77e7640c5..bf076d74ca41e4 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -1230,6 +1230,57 @@ parsing their headers, those should be included after the import. If the
 imported modules don't provide such a header, one can be made manually for
 improved compile time performance.
 
+Reachability of internal partition units
+----------------------------------------
+
+The internal partition units are called as implementation partition unit somewhere else.
+But the name may be confusing since implementation partition units are not implementation
+units.
+
+According to [module.reach]p1,2:
+
+  A translation unit U is necessarily reachable from a point P if U is a module
+  interface unit on which the translation unit containing P has an interface
+  dependency, or the translation unit containing P imports U, in either case
+  prior to P.
+
+  All translation units that are necessarily reachable are reachable. Additional
+  translation units on which the point within the program has an interface
+  dependency may be considered reachable, but it is unspecified which are and
+  under what circumstances.
+
+For example,
+
+.. code-block:: c++
+
+  // a.cpp
+  import B;
+  int main()
+  {
+      g<void>();
+  }
+
+  // b.cppm
+  export module B;
+  import :C;
+  export template <typename T> inline void g() noexcept
+  {
+      return f<T>();
+  }
+
+  // c.cppm
+  module B:C;
+  template<typename> inline void f() noexcept {}
+
+The internal partition units ``c.cppm`` is not necessarily reachable to
+``a.cpp`` since ``c.cppm`` is not a module interface unit and ``a.cpp``
+doesn't import ``c.cppm``. Then it is up to the compiler to decide if
+``c.cppm`` is reachable to ``a.cpp`` or not. Clang's decision is the
+non-directly imported internal partition units are not reachable.
+
+The suggestion to use internal partition units is, only import them in
+the implementation units unless we understand the codebases very well.
+
 Known Issues
 ------------
 

>From 97897c48a7fa0af7e63a894abdb8648335b29918 Mon Sep 17 00:00:00 2001
From: Chuanqi Xu <yedeng.yd at linux.alibaba.com>
Date: Mon, 12 Aug 2024 10:22:02 +0800
Subject: [PATCH 2/3] address comments

---
 clang/docs/StandardCPlusPlusModules.rst | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index bf076d74ca41e4..7ed05aad76ba8d 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -1233,11 +1233,12 @@ improved compile time performance.
 Reachability of internal partition units
 ----------------------------------------
 
-The internal partition units are called as implementation partition unit somewhere else.
-But the name may be confusing since implementation partition units are not implementation
+The internal partition units are sometimes called implementation partition units in other documentation.
+However, the name may be confusing since implementation partition units are not implementation
 units.
 
-According to [module.reach]p1,2:
+According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
+`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_:
 
   A translation unit U is necessarily reachable from a point P if U is a module
   interface unit on which the translation unit containing P has an interface
@@ -1272,14 +1273,14 @@ For example,
   module B:C;
   template<typename> inline void f() noexcept {}
 
-The internal partition units ``c.cppm`` is not necessarily reachable to
-``a.cpp`` since ``c.cppm`` is not a module interface unit and ``a.cpp``
-doesn't import ``c.cppm``. Then it is up to the compiler to decide if
-``c.cppm`` is reachable to ``a.cpp`` or not. Clang's decision is the
-non-directly imported internal partition units are not reachable.
+The internal partition unit ``c.cppm`` is not necessarily reachable by
+``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``
+doesn't import ``c.cppm``. This leaves it up to the compiler to decide if
+``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that
+indirectly imported internal partition units are not reachable.
 
-The suggestion to use internal partition units is, only import them in
-the implementation units unless we understand the codebases very well.
+The suggested approach for using an internal partition unit in Clang is
+to only import them in the implementation unit.
 
 Known Issues
 ------------

>From ed0b28176b514882aaecd51a5f81c0eeef61ee3c Mon Sep 17 00:00:00 2001
From: Chuanqi Xu <yedeng.yd at linux.alibaba.com>
Date: Tue, 13 Aug 2024 16:33:09 +0800
Subject: [PATCH 3/3] add version for docs

---
 clang/docs/StandardCPlusPlusModules.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 7ed05aad76ba8d..ccc0cb59f8e710 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -1238,7 +1238,7 @@ However, the name may be confusing since implementation partition units are not
 units.
 
 According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
-`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_:
+`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):
 
   A translation unit U is necessarily reachable from a point P if U is a module
   interface unit on which the translation unit containing P has an interface