[clang] Revise the modules document for clarity (PR #90237)

Chuanqi Xu via cfe-commits cfe-commits at lists.llvm.org
Sat Apr 27 20:05:18 PDT 2024


================
@@ -925,45 +923,41 @@ In that case, you need to convert your source files (.cpp files) to module imple
   // Following off should be unchanged.
   ...
 
-The module implementation unit will import the primary module implicitly.
-We don't include any headers in the module implementation units
-here since we want to avoid duplicated declarations between translation units.
-This is the reason why we add non-exported using declarations from the third
-party libraries in the primary module interface unit.
+The module implementation unit will import the primary module implicitly. Do
+not include any headers in the module implementation units because that avoids
+duplicated declarations between translation units. This is why non-exported
+using declarations are added from third-party libraries in the primary module
+interface unit.
 
-And if you provide your library as ``libyour_library.so``, you probably need to
-provide a modular one ``libyour_library_modules.so`` since you changed the ABI.
+If the library is provided as ``libyour_library.so``, a modular library (e.g.,
+``libyour_library_modules.so``) may also need to be provided for ABI
+compatibility.
 
 What if there are headers only inclued by the source files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The above practice may be problematic if there are headers only included by the source
-files. If you're using private module fragment, you may solve the issue by including them
-in the private module fragment. While it is OK to solve it by including the implementation
-headers in the module purview if you're using implementation module units, it may be
-suboptimal since the primary module interface units now containing entities not belongs
-to the interface.
-
-If you're a perfectionist, maybe you can improve it by introducing internal module partition unit.
+The above practice may be problematic if there are headers only included by the
+source files. When using a private module fragment, this issue may be solved by
+including those headers in the private module fragment. While it is OK to solve
+it by including the implementation headers in the module purview when using
+implementation module units, it may be suboptimal because the primary module
+interface units now contain entities that do not belong to the interface.
 
-The internal module partition unit is an importable module unit which is internal
-to the module itself. The concept just meets the headers only included by the source files.
-
-We don't show code snippet since it may be too verbose or not good or not general.
-But it may not be too hard if you can understand the points of the section.
+This can potentially be improved by introducing module partition implementation
+unit. The module partition implementation unit is an importable module unit
+which is internal to the module itself. However, this approach may not always
+be the best way forward.
----------------
ChuanqiXu9 wrote:

Maybe I misunderstand the sentence "However, this approach may not always
be the best way forward." But it reads as, it is not good to use `module partition implementation unit`. This is not true.

https://github.com/llvm/llvm-project/pull/90237


More information about the cfe-commits mailing list