resolve problems mentioned in code review ...

1. Reverted `extract_example_code_from_docs.py`.
2. Added "Module definition:" and "Client:" to cpp20_modules_support.md,
to exclude it from the doc test generator.
3. Minor formatting issues (trailing EOL, empty lines ...) are fixed.

Author: SidneyCogdill

.github/workflows/bvt-appleclang.yml

@@ -20,7 +20,7 @@ jobs:
 
     - name: build and run test with AppleClang
       run: |
-        cmake -B build -GNinja -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build -GNinja -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-clang.yml

@@ -26,7 +26,7 @@ jobs:
 
     - name: build and run test with clang 20
       run: |
-        cmake -B build -GNinja -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-compatibility.yml

@@ -28,37 +28,37 @@ jobs:
 
     - name: build and run test with gcc 14
       run: |
-        cmake -B build-gcc-14 -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build-gcc-14 -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build-gcc-14 -j
         ctest --test-dir build-gcc-14 -j
 
     - name: build and run test with gcc 13
       run: |
-        cmake -B build-gcc-13 -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build-gcc-13 -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-gcc-13 -j
         ctest --test-dir build-gcc-13 -j
 
     - name: build and run test with clang 19
       run: |
-        cmake -B build-clang-19 -DCMAKE_C_COMPILER=clang-19 -DCMAKE_CXX_COMPILER=clang++-19 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build-clang-19 -DCMAKE_C_COMPILER=clang-19 -DCMAKE_CXX_COMPILER=clang++-19 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-clang-19 -j
         ctest --test-dir build-clang-19 -j
 
     - name: build and run test with clang 18
       run: |
-        cmake -B build-clang-18 -DCMAKE_C_COMPILER=clang-18 -DCMAKE_CXX_COMPILER=clang++-18 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build-clang-18 -DCMAKE_C_COMPILER=clang-18 -DCMAKE_CXX_COMPILER=clang++-18 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-clang-18 -j
         ctest --test-dir build-clang-18 -j
 
     - name: build and run test with clang 17
       run: |
-        cmake -B build-clang-17 -DCMAKE_C_COMPILER=clang-17 -DCMAKE_CXX_COMPILER=clang++-17 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build-clang-17 -DCMAKE_C_COMPILER=clang-17 -DCMAKE_CXX_COMPILER=clang++-17 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-clang-17 -j
         ctest --test-dir build-clang-17 -j
 
     # Note that libc++ in Clang 19 is not compatible with Clang 16. Therefore, we fallback to libstdc++.
     - name: build and run test with clang 16
       run: |
-        cmake -B build-clang-16 -DCMAKE_C_COMPILER=clang-16 -DCMAKE_CXX_COMPILER=clang++-16 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build-clang-16 -DCMAKE_C_COMPILER=clang-16 -DCMAKE_CXX_COMPILER=clang++-16 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-clang-16 -j
         ctest --test-dir build-clang-16 -j

.github/workflows/bvt-gcc.yml

@@ -23,7 +23,7 @@ jobs:
 
     - name: build and run test with gcc 14
       run: |
-        cmake -B build -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-msvc.yml

@@ -18,7 +18,7 @@ jobs:
 
     - name: build and run test with MSVC
       run: |
-        cmake -B build -DCMAKE_CXX_STANDARD=23
+        cmake -B build -DCMAKE_CXX_STANDARD=23 -DPROXY_BUILD_MODULES=TRUE
         cmake --build build --config Release -j
         ctest --test-dir build -j
         mkdir build\drop > $null

.github/workflows/bvt-nvhpc.yml

@@ -23,7 +23,7 @@ jobs:
     - name: build and run test with NVHPC 24.9
       run: |
         PATH=/opt/nvidia/hpc_sdk/Linux_x86_64/24.9/compilers/bin:$PATH; export PATH
-        cmake -B build -GNinja -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++ -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILDING_WITH_MODULE=FALSE
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++ -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

CMakeLists.txt

@@ -13,9 +13,9 @@ endif()
 
 if(PROJECT_IS_TOP_LEVEL)
   option(
-    PROXY_BUILDING_WITH_MODULE 
+    PROXY_BUILD_MODULES 
     "When this project is top level, build the docs and tests with C++ module support."
-    ON
+    OFF
   )
 endif()
 
@@ -38,7 +38,7 @@ target_include_directories(msft_proxy INTERFACE $<BUILD_INTERFACE:${CMAKE_CURREN
 # Do not set the module target if proxy is consumed as a subdirectory.
 if(PROJECT_IS_TOP_LEVEL)
   set(proxy_INCLUDE_DIR include)
-  if(PROXY_BUILDING_WITH_MODULE)
+  if(PROXY_BUILD_MODULES)
     include(cmake/proxyModuleTargets.cmake)
   endif()
 else()

docs/cpp20_modules_support.cmake.in

@@ -1,4 +1,4 @@
-if(PROXY_BUILDING_WITH_MODULE)
+if(PROXY_BUILD_MODULES)
   add_executable($NAME$ code_2.cpp)
 
   target_link_libraries($NAME$ msft_proxy::module)

docs/cpp20_modules_support.md

@@ -1,14 +1,14 @@
 # C++20 Modules support
 
-proxy ships with `.ixx` files starting with version **4.0.0**. Compared to traditional headers, modules offer faster compilation speed and isolation against preprocessor macro definitions.
+The "Proxy" library ships with `.ixx` files starting with version **4.0.0**. Compared to traditional headers, modules offer faster compilation speed and isolation against preprocessor macro definitions.
 
 As of 2025-05-11, CMake lacks support for forward compatibility when consuming C++ modules, which causes consumers with newer C++ standard to be unable to use modules with older standard. Until this is implemented by CMake, a CMake target containing the module can be manually declared using the following CMake script:
 
 ```cmake
 find_package(proxy REQUIRED)
 
 if(NOT DEFINED proxy_INCLUDE_DIR) # [1]
-    message(FATAL_ERROR "proxy_INCLUDE_DIR must be defined to use this script.")
+  message(FATAL_ERROR "proxy_INCLUDE_DIR must be defined to use this script.")
 endif()
 
 message(STATUS "Declaring `msft_proxy::module` target for include path ${proxy_INCLUDE_DIR}")
@@ -32,8 +32,8 @@ target_compile_features(msft_proxy_module PUBLIC cxx_std_20) # [2]
 target_link_libraries(msft_proxy_module PUBLIC msft_proxy)
 ```
 
-- [1] `proxy_INCLUDE_DIR` is automatically declared after `find_package(proxy)`
-- [2] The C++ standard version for `msft_proxy_module` target should be the same or higher than the consumer CMake target. For example if your project is using C++23 mode, this line should be changed to `cxx_std_23` or `cxx_std_26` / newer standards.
+- (1) `proxy_INCLUDE_DIR` is automatically declared after `find_package(proxy)`
+- (2) The C++ standard version for `msft_proxy_module` target should be the same or higher than the consumer CMake target. For example if your project is using C++23 mode, this line should be changed to `cxx_std_23` or `cxx_std_26` / newer standards.
 
 It can then be consumed like this:
 
@@ -43,19 +43,21 @@ target_link_libraries(main PRIVATE msft_proxy::module)
 
 ## Example
 
+Module definition:
+
 ```cpp
 // dictionary.cpp
 module;
 
-#include <string> // [1]
+#include <string> // (1)
 
-#include <proxy/proxy_macros.h> // [2]
+#include <proxy/proxy_macros.h> // (2)
 
 export module dictionary;
 
-import proxy; // [3]
+import proxy; // (3)
 
-extern "C++" { // [4]
+extern "C++" { // (4)
 PRO_DEF_MEM_DISPATCH(MemAt, at);
 }
 
@@ -65,6 +67,8 @@ export struct Dictionary : pro::facade_builder
 
 ```
 
+Client:
+
 ```cpp
 // main.cpp
 #include <vector>
@@ -81,8 +85,8 @@ int main() {
 
 ```
 
-- [1] This is a traditional header rather than a module. It should be declared in global fragment (after `module` and before `export module`).
-- [2] This makes all `PRO_DEF_` macros available. This header file contains only some macros and are therefore very fast to compile. 
-- [3] `import proxy;` makes all public interfaces from `pro` namespace available in the current translation unit.
-- [4] As of 2025-05-11, clangd requires the accessor struct to be either `export`-ed, or be declared within an `extern "C++"` block, in order to have auto completion working.
+- (1) This is a traditional header rather than a module. It should be declared in global fragment (after `module` and before `export module`).
+- (2) This makes all `PRO_DEF_` macros available. This header file contains only some macros and are therefore very fast to compile. 
+- (3) `import proxy;` makes all public interfaces from `pro` namespace available in the current translation unit.
+- (4) As of 2025-05-11, clangd requires the accessor struct to be either `export`-ed, or be declared within an `extern "C++"` block, in order to have auto completion working.
 

include/proxy/proxy.ixx

@@ -89,4 +89,4 @@ using std::formatter;
 export namespace pro::details {
 using details::adl_accessor_arg_t;
 using details::non_proxy_arg;
-} // namespace pro::details
+} // namespace pro::details

include/proxy/proxy_macros.h

@@ -180,4 +180,4 @@ ___PRO_DEBUG( \
 #define PRO_DEF_FREE_AS_MEM_DISPATCH(__NAME, ...) \
     ___PRO_EXPAND_MACRO(___PRO_DEF_FREE_AS_MEM_DISPATCH, __NAME, __VA_ARGS__)
 
-#endif // _MSFT_PROXY_MACROS_
+#endif // _MSFT_PROXY_MACROS_

tests/cpp20_modules/CMakeLists.txt

@@ -1,23 +1,18 @@
 
-if(PROXY_BUILDING_WITH_MODULE)
-
+if(PROXY_BUILD_MODULES)
   add_executable(msft_proxy_tests_cpp20_modules
     main.cpp
   )
-
   target_sources(msft_proxy_tests_cpp20_modules
     PRIVATE
       FILE_SET CXX_MODULES FILES
       foo.cpp
       impl.cpp
   )
-
   target_compile_features(
     msft_proxy_tests_cpp20_modules
     PRIVATE
     cxx_std_20
   )
-
   target_link_libraries(msft_proxy_tests_cpp20_modules PRIVATE msft_proxy msft_proxy::module)
-
-endif()
+endif()

tests/cpp20_modules/foo.cpp

@@ -16,10 +16,10 @@ PRO_DEF_FREE_AS_MEM_DISPATCH(FreeGetBaz, GetBaz);
 }
 
 export struct Foo
-    : pro::facade_builder ::add_convention<MemGetFoo, int() const>::build {};
+    : pro::facade_builder::add_convention<MemGetFoo, int() const>::build {};
 
 export struct Bar
-    : pro::facade_builder ::add_convention<FreeGetBar, int() const>::build {};
+    : pro::facade_builder::add_convention<FreeGetBar, int() const>::build {};
 
 export struct Baz
-    : pro::facade_builder ::add_convention<FreeGetBaz, int() const>::build {};
+    : pro::facade_builder::add_convention<FreeGetBaz, int() const>::build {};