[clang] 04fb3e3 - [C++20] [Modules] Document the behavior about reserved module names

[Chuanqi Xu via cfe-commits]

Author: Chuanqi Xu
Date: 2022-11-10T16:43:50+08:00
New Revision: 04fb3e3de7329a11b75c77fc418e3e5f5ddcac77

URL: https://github.com/llvm/llvm-project/commit/04fb3e3de7329a11b75c77fc418e3e5f5ddcac77
DIFF: https://github.com/llvm/llvm-project/commit/04fb3e3de7329a11b75c77fc418e3e5f5ddcac77.diff

LOG: [C++20] [Modules] Document the behavior about reserved module names

We would diagnose about the reserved names in b8ceb9f4e4bd. And the
patch documents about the related behaviors.

Added: 
    

Modified: 
    clang/docs/StandardCPlusPlusModules.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 021edbc3dfdf..c9790703e2ee 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -270,6 +270,40 @@ we can't compile them by the original command lines. But we are still able to do
   $ ./Hello.out
   Hello World!
 
+Module name requirement
+~~~~~~~~~~~~~~~~~~~~~~~
+
+[module.unit]p1 says:
+
+> All module-names either beginning with an identifier consisting of std followed by zero
+  or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not
+  be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
+  module-name is a reserved identifier, the module name is reserved for use by C++ implementations;
+  otherwise it is reserved for future standardization.
+
+So all of the following name is not valid by default:
+
+.. code-block:: text
+
+    std
+    std1
+    std.foo
+    __test
+    // and so on ...
+
+If you still want to use the reserved module names for any reason, currently you can add a special line marker
+in the front of the module declaration like:
+
+.. code-block:: c++
+
+  # __LINE_NUMBER__ __FILE__ 1 3
+  export moudle std;
+
+Here the `__LINE_NUMBER__` is the actual line number of the corresponding line. The `__FILE__` means the filename
+of the translation unit. The `1` means the following is a new file. And `3` means this is a system header/file so
+the certain warnings should be suppressed. You could find more details at:
+https://gcc.gnu.org/onlinedocs/gcc-3.0.2/cpp_9.html.
+
 How to specify the dependent BMIs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~