[PATCH] D131388: [docs] Add "C++20 Modules"

[Iain Sandoe via Phabricator via cfe-commits]

iains added a comment.

general comment.

Do we encourage contractions (don't, can't) etc. in documentation?
I would suggest that to assist in any translation process it is better to write "do not" or "can not" instead (but that's just an opinion, not a matter of correctness).



================
Comment at: clang/docs/CPlusPlus20Modules.rst:20-22
+more about the general idea of modules. Due to the C++20 modules having very
+different semantics, it might be more friendly for users who care about C++20
+modules only to create a new page.
----------------
I do not think we need to justify the existence of the page, just identify its purpose - maybe like:

"Since C++20 modules have different semantics (and work flows) from `Clang modules this page describes the background and use of Clang with C++20 modules."


================
Comment at: clang/docs/CPlusPlus20Modules.rst:25-26
+Although the term ``modules`` has a unique meaning in C++20 Language Specification,
+when people talk about C++20 modules, they may refer to another C++20 feature:
+header units. Therefore, this document will try to cover header units as well.
+
----------------
this also includes `C++20 header units`, which are also covered in this document.



================
Comment at: clang/docs/CPlusPlus20Modules.rst:57
+A module consists of one or more module units. A module unit is a special
+translation unit. Every module unit should have a module declaration. The syntax
+of the module declaration is:
----------------
must


================
Comment at: clang/docs/CPlusPlus20Modules.rst:219
+Currently, C++20 Modules are enabled automatically if the language standard is ``-std=c++20`` or newer.
+The ``-fmodules-ts`` option is deprecated and is planned to be removed.
+
----------------
procedural point: do we ever actually remove an existing option - or does it just become a "NOP"?


================
Comment at: clang/docs/CPlusPlus20Modules.rst:259
+
+Remember to linking module files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------
link


================
Comment at: clang/docs/CPlusPlus20Modules.rst:458
+
+The declarations in module unit which are not in global module fragment would get new linkage names.
+
----------------
The declarations in a module unit which are not in global module fragment have new linkage names.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:592
+
+But what's different is that we can't use ``-fprebuilt-module-path`` to search the module file for header units.
+
----------------
With the existing implementation ``-fprebuilt-module-path`` cannot be used for header units (since they are nominally anonymous).  For header units use  ``-fmodule-file`` to include the relevant PCM file for each header unit.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:594-595
+
+(This may be an implementation defect. Although we could argue that header units have no name according to the spec,
+it is natural that we couldn't search it. But this is not user friendly enough.)
+
----------------
Notes ( we have an internal implementation name, which can be used by planned tooling and/or mapping changes)

--- so maybe:

this is expect to be solved in future editions of the compiler either by the tooling finding and specifying the -fmodule-file or by the use of a module-mapper that understands how to map the header name to their PCMs.




Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388