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

[David Blaikie via Phabricator via cfe-commits]

dblaikie added inline comments.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:31
+
+This document was intended to be a manual first and foremost, however, we consider it helpful to
+introduce some language background here for readers who are not familiar with
----------------



================
Comment at: clang/docs/CPlusPlus20Modules.rst:122
+
+Let's see a "hello world" example to use modules.
+
----------------



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



================
Comment at: clang/docs/CPlusPlus20Modules.rst:312-321
+Note that **currently** the compiler doesn't consider inconsistent macro definition a problem. For example:
+
+.. code-block:: console
+
+  $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+  # Inconsistent optimization level.
+  $ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
----------------
this sort of aside might be best left for a separate part of the document - an FAQ/side-notes (a footnote, perhaps?), etc to keep the rest of the document more focussed?


================
Comment at: clang/docs/CPlusPlus20Modules.rst:347
+  $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+  $ rm -f M.cppm
+  $ clang++ -std=c++20 Use.cpp -fmodule-file=M.pcm
----------------
Could probably skip the `-f`?


================
Comment at: clang/docs/CPlusPlus20Modules.rst:395-396
+
+Roughly, this theory is correct. But the problem is that it is too rough. Let's see what actually happens.
+For example, the behavior also depends on the optimization level, as we will illustrate below.
+
----------------
I'm not sure I'm able to follow the example and how it justifies the rough theory as inadequate to explain the motivation for modules - could you clarify more directly (in comments, and then we can discuss how to word it) what the motivation for this section is/what you're trying to convey?


================
Comment at: clang/docs/CPlusPlus20Modules.rst:610
+
+Another difference with modules is that we can't compile the module file.
+It makes sense due to the semantics of header units, which are just like headers.
----------------
Might need some more words here - I guess this means "there is no .o for a .pcm from a header unit" basically?


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

https://reviews.llvm.org/D131388