[clang] 684955a - [Modules] [doc] Document the problem that we can't include headers before import declarations

[Chuanqi Xu via cfe-commits]

Author: Chuanqi Xu
Date: 2023-03-17T15:10:37+08:00
New Revision: 684955a2302daacb4136b0247c00f6f95472614b

URL: https://github.com/llvm/llvm-project/commit/684955a2302daacb4136b0247c00f6f95472614b
DIFF: https://github.com/llvm/llvm-project/commit/684955a2302daacb4136b0247c00f6f95472614b.diff

LOG: [Modules] [doc] Document the problem that we can't include headers before import declarations

Added: 
    

Modified: 
    clang/docs/StandardCPlusPlusModules.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.rst
index 970803b56c8c6..ab34ba03ba14c 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -616,6 +616,50 @@ and add the label ``clang:modules`` (if you have permissions for that).
 
 For higher level support for proposals, you could visit https://clang.llvm.org/cxx_status.html.
 
+Including headers after import is problematic
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example, the following example can be accept:
+
+.. code-block:: c++
+
+  #include <iostream>
+  import foo; // assume module 'foo' contain the declarations from `<iostream>`
+
+  int main(int argc, char *argv[])
+  {
+      std::cout << "Test\n";
+      return 0;
+  }
+
+but it will get rejected if we reverse the order of ``#include <iostream>`` and
+``import foo;``:
+
+.. code-block:: c++
+
+  import foo; // assume module 'foo' contain the declarations from `<iostream>`
+  #include <iostream>
+
+  int main(int argc, char *argv[])
+  {
+      std::cout << "Test\n";
+      return 0;
+  }
+
+Both of the above examples should be accepted.
+
+This is a limitation in the implementation. In the first example,
+the compiler will see and parse <iostream> first then the compiler will see the import.
+So the ODR Checking and declarations merging will happen in the deserializer.
+In the second example, the compiler will see the import first and the include second.
+As a result, the ODR Checking and declarations merging will happen in the semantic analyzer.
+
+So there is divergence in the implementation path. It might be understandable that why
+the orders matter here in the case.
+(Note that "understandable" is 
diff erent from "makes sense").
+
+This is tracked in: https://github.com/llvm/llvm-project/issues/61465
+
 Ambiguous deduction guide
 ~~~~~~~~~~~~~~~~~~~~~~~~~