[Doc] [C++20] [Modules] Clarify the reachability of internal partition units

[ChuanqiXu9]

Motivated by #101348

Although I don't want the tool's doc to explain the standard's wording, the wording itself has some unspecified thing. So I feel it will be helpful to make it clear. At least it may help us receive less invalid issue reports.

[llvmbot]

@llvm/pr-subscribers-clang-modules

@llvm/pr-subscribers-clang

Author: Chuanqi Xu (ChuanqiXu9)

Changes

Motivated by #101348

Although I don't want the tool's doc to explain the standard's wording, the wording itself has some unspecified thing. So I feel it will be helpful to make it clear. At least it may help us receive less invalid issue reports.

---

Full diff: https://github.com/llvm/llvm-project/pull/102572.diff

1 Files Affected:

• (modified) clang/docs/StandardCPlusPlusModules.rst (+51)

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
 ------------
 

[AaronBallman]

Thank you for the improved documentation! I made some suggestions for clarity, but please make sure I didn't change your intended meaning.

[AaronBallman]

Suggested change

	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.
	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.

[ChuanqiXu9]

done

[AaronBallman]

It'd be good to specify which standard version you pulled the wording from.

[ChuanqiXu9]

It was from the draft version (https://eel.is/c++draft/module.reach#1). I changed it to the links. Hope this helps.

[AaronBallman]

Links only sort of help -- because they're live links, they get out of date very quickly. Putting a standard version number there helps the reader to understand which standard the quote was true for and they can hunt for the wording in the latest draft from there.

[AaronBallman]

Suggested change

	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.

[ChuanqiXu9]

Done

[AaronBallman]

Suggested change

	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.

[ChuanqiXu9]

Done

[AaronBallman]

LGTM