[clang] [docs] Asking to test serialization/deserialization for new C++ feature (PR #200994)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 updated https://github.com/llvm/llvm-project/pull/200994

>From 75b4db9622aec2aab55e410b3eeefa92eb53421b Mon Sep 17 00:00:00 2001
From: Chuanqi Xu <yedeng.yd at linux.alibaba.com>
Date: Tue, 2 Jun 2026 11:17:01 +0800
Subject: [PATCH 1/2] [docs] Asking to test serialization/deserialization for
 new C++ feature

---
 clang/docs/InternalsManual.rst | 70 ++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst
index 2dab979dac3e4..d98c79b60741c 100644
--- a/clang/docs/InternalsManual.rst
+++ b/clang/docs/InternalsManual.rst
@@ -3908,6 +3908,76 @@ directives:
     //   since-cxx17-note@#cwg92-p {{use 'noexcept(false)' instead}}
     // cxx98-14-error@#cwg92-p {{target exception specification is not superset of source}}
 
+
+Testing Modules (Serialization/Deserialization) When implementing a new C++ syntax
+----------------------------------------------------------------------------------
+
+When we implement a new C++ syntax, we need to make sure that it works correctly with modules.
+This means that we need to test that the syntax can be serialized and deserialized (if needed)
+correctly when used in a module. Otherwise, we can't claim the new C++ syntax is supported.
+
+To test a syntax that can be serialized, we can use the syntax in a module interface unit.
+(For ease of description, we use contracts as the example here)
+
+.. code-block:: c++
+
+  export module m;
+  void func(int x) pre(x > 0) {}
+  void func(int x, int y) pre(x > 0) pre(x > 0) {}
+  int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; }
+
+And to test a syntax can be deserialized, we can import the module and use the entity (if any)
+defined with the syntax in the module interface.
+
+.. code-block:: c++
+
+  import m;
+  int test() {
+    func(1);
+    func(1, 2);
+    int x = func(1, 2, 3);
+    return x;
+  }
+
+These tests should be put into ``clang/test/Modules`` directory. We can use ``split-file`` tool
+to put multiple files into a single test file. To serialize a module interface unit to a BMI (built
+module interface), we can use the ``-emit-reduced-module-interface`` option. To deserialize the
+corresponding module interface unit, we can use ``-fmodule-file=<module-name>=<bmi-file-path>`` option.
+
+Put the above things together, we have
+
+.. code-block:: c++
+
+  // RUN: rm -rf %t
+  // RUN: mkdir -p %t
+  // RUN: split-file %s %t
+  //
+  // RUN: %clang_cc1 -std=c++26 %t/m.cppm -emit-reduced-module-interface -o %t/m.pcm
+  // RUN: %clang_cc1 -std=c++26 %t/use.cc -fmodule-file=m=%t/m.pcm -verify -syntax-only
+
+  //--- m.cppm
+  export module m;
+  void func(int x) pre(x > 0) {}
+  void func(int x, int y) pre(x > 0) pre(x > 0) {} // test we can serialize multiple pre conditions.
+  int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; }
+
+  //--- use.cc
+  // expected-no-diagnostics
+  import m;
+  int test() {
+    func(1);
+    func(1, 2);
+    int x = func(1, 2, 3);
+    return x;
+  }
+
+We don't have to test all possible syntax combinations, which would be impractical.
+It is fine to test that the syntax construct can be serialized and deserialized.
+
+For example, for contracts, if we choose to implement it as a member of ``FunctionDecl``,
+and if the data structure of contracts is not affected by whether the FunctionDecl is a
+CXXMethodDecl or not we don't have to test the contracts in the case of member functions.
+
 Feature Test Macros
 ===================
 Clang implements several ways to test whether a feature is supported or not.

>From 58c722ba0a1de44fc179e499c3d885963bf21975 Mon Sep 17 00:00:00 2001
From: Chuanqi Xu <yedeng.yd at linux.alibaba.com>
Date: Thu, 4 Jun 2026 13:50:56 +0800
Subject: [PATCH 2/2] Update

---
 clang/docs/InternalsManual.rst | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst
index d98c79b60741c..18d269c657df5 100644
--- a/clang/docs/InternalsManual.rst
+++ b/clang/docs/InternalsManual.rst
@@ -3912,12 +3912,12 @@ directives:
 Testing Modules (Serialization/Deserialization) When implementing a new C++ syntax
 ----------------------------------------------------------------------------------
 
-When we implement a new C++ syntax, we need to make sure that it works correctly with modules.
-This means that we need to test that the syntax can be serialized and deserialized (if needed)
-correctly when used in a module. Otherwise, we can't claim the new C++ syntax is supported.
+When implementing C++ functionality, it must work correctly with modules before
+claiming the feature is fully supported. This may require adding test coverage for
+serialization and deserialization of C++ modules using the feature.
 
-To test a syntax that can be serialized, we can use the syntax in a module interface unit.
-(For ease of description, we use contracts as the example here)
+To test serialization, the feature can be tested in a module interface unit.
+(For ease of description, contracts are used as the example here.)
 
 .. code-block:: c++
 
@@ -3926,8 +3926,8 @@ To test a syntax that can be serialized, we can use the syntax in a module inter
   void func(int x, int y) pre(x > 0) pre(x > 0) {}
   int func(int x, int y, int z) pre(x > 0) pre(y > 0) pre(z > 0) post(r: r > 0) { return 1; }
 
-And to test a syntax can be deserialized, we can import the module and use the entity (if any)
-defined with the syntax in the module interface.
+To test deserialization, the serialized module can be imported to validate the behavior
+of the feature in the module interface.
 
 .. code-block:: c++
 
@@ -3939,10 +3939,11 @@ defined with the syntax in the module interface.
     return x;
   }
 
-These tests should be put into ``clang/test/Modules`` directory. We can use ``split-file`` tool
-to put multiple files into a single test file. To serialize a module interface unit to a BMI (built
-module interface), we can use the ``-emit-reduced-module-interface`` option. To deserialize the
-corresponding module interface unit, we can use ``-fmodule-file=<module-name>=<bmi-file-path>`` option.
+These tests should be put into ``clang/test/Modules`` directory. The ``split-file`` tool
+can be used to split a single test file into multiple logical files To serialize a module
+interface unit to a BMI (built module interface), we the ``-emit-reduced-module-interface``
+option can be used. To deserialize the corresponding module interface unit, the
+``-fmodule-file=<module-name>=<bmi-file-path>`` option can be used.
 
 Put the above things together, we have