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

[Aaron Ballman via cfe-commits]

================
@@ -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.
----------------
AaronBallman wrote:

> “There is no need to add a serialization RUN line to every test” This sounds odd and confusing. I can't figure out its meaning as a dev reader.

Fair! I was mostly trying to convey that the goal isn't to reproduce every semantic test with an additional serialization test.

> hmmm Maybe it is fine to say we won't test all combinations. WDYT? I feel this is natural?

Yeah, I could go with that combined with part of what I was suggesting. How about:

The tests for serialization and deserialization are expected to ensure that the data contained by the AST node is properly saved and reconstituted. Serialization tests do not need to exhaustively test all possible ways the AST node can be used in source, they only need to validate that the internal state of the AST node can be round-tripped through serialization.

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