Added documentation

Author: liuzicheng1987

README.md

@@ -53,6 +53,7 @@ reflect-cpp and sqlgen fill important gaps in C++ development. They reduce boile
 
 ### More in our [documentation](https://rfl.getml.com):
   - [Installation ↗](https://rfl.getml.com/install/#option-2-compilation-using-cmake)
+  - [C++26 reflection ↗](https://rfl.getml.com/cpp26_reflection)
   - [Benchmarks ↗](https://rfl.getml.com/benchmarks)
   - [How to contribute ↗](https://rfl.getml.com/contributing)
   - [Compiling and running the tests ↗](https://rfl.getml.com/contributing/#compiling-and-running-the-tests)
@@ -676,6 +677,21 @@ The following compilers are supported for C++-20:
 The following compilers are supported for C++-26:
 - GCC 16.2 or higher
 
+### Compiling with C++-26 reflection
+
+To compile reflect-cpp using the standard C++ reflection facilities, pass the CMake option
+`REFLECTCPP_USE_CPP26_REFLECTION` together with the compiler flag that activates reflection
+support in your compiler (`-freflection` for GCC, `-freflection-latest` for Clang):
+
+```bash
+cmake -S . -B build -DCMAKE_CXX_STANDARD=26 -DCMAKE_BUILD_TYPE=Release -DREFLECTCPP_USE_CPP26_REFLECTION=ON -DCMAKE_CXX_FLAGS="-freflection"
+cmake --build build -j 4
+```
+
+With C++-26 reflection, fixed-size C arrays and inheritance are supported out of the box (no
+`-DREFLECT_CPP_C_ARRAYS_OR_INHERITANCE` flag needed), and there are no range restrictions for
+enums. Refer to the [documentation](https://rfl.getml.com/cpp26_reflection) for details.
+
 ### Using vcpkg
 
 https://vcpkg.io/en/package/reflectcpp

docs/c_arrays_and_inheritance.md

@@ -12,6 +12,13 @@ inheritance altogether.
 Note that C arrays are not the same thing as `std::array`. `std::array` is always
 supported and is the recommended alternative.
 
+!!! note "C++-26 reflection"
+
+    If you compile reflect-cpp with C++-26 reflection (see [C++26 reflection](cpp26_reflection.md)),
+    then none of the restrictions in this section apply: fixed-size C arrays and inheritance are
+    supported out of the box, no flag is required, and the fields may be spread out over
+    multiple structs.
+
 If you want support for these, you will have to pass the flag `-D REFLECT_CPP_C_ARRAYS_OR_INHERITANCE`
 during compilation.
 
@@ -85,6 +92,10 @@ struct Derived : Base {
 };
 ```
 
+Note that this restriction does not apply when compiling with C++-26 reflection: with C++-26,
+the fields of the base class and the fields of the derived class are combined automatically,
+so the example above works as well.
+
 The recommended alternative is to simply use `rfl::Flatten`, which
 has no such limitation:
 

docs/cpp26_reflection.md

@@ -0,0 +1,126 @@
+# C++26 reflection
+
+reflect-cpp can be compiled in two modes, which use two different reflection implementations:
+
+* **C++-20/23 mode (the default):** reflection is implemented using metaprogramming
+  techniques (structured bindings, aggregate-initialization analysis, and
+  [enchantum](https://github.com/ZXShady/enchantum)). This works on a wide range of
+  compilers, but it has some limitations and comes with a higher compile-time cost.
+* **C++-26 mode:** reflection uses the standard C++ reflection facilities
+  (`<meta>`, [P2996](https://wg21.link/P2996)). This is more powerful, because members
+  and enumerators are queried directly from the compiler instead of being inferred.
+
+C++-26 mode is opt-in. It requires a compiler that supports the C++ reflection proposal
+and a compiler flag to activate it. The rest of this documentation applies to both modes,
+except where explicitly noted otherwise.
+
+## Compiling with C++-26 reflection
+
+The following compilers are supported for C++-26:
+
+* GCC 16.2 or higher
+* Clang: experimental, only available in Clang builds that implement
+  [P2996](https://wg21.link/P2996) (such as Bloomberg's
+  [clang-p2996](https://github.com/bloomberg/clang-p2996) fork)
+
+To compile reflect-cpp with C++-26 reflection, pass the CMake option
+`REFLECTCPP_USE_CPP26_REFLECTION` and the compiler flag that activates reflection
+support in your compiler:
+
+* GCC: `-freflection`
+* Clang: `-freflection-latest`
+
+For example, using cmake:
+
+```bash
+cmake -S . -B build -DCMAKE_CXX_STANDARD=26 -DCMAKE_BUILD_TYPE=Release -DREFLECTCPP_USE_CPP26_REFLECTION=ON -DCMAKE_CXX_FLAGS="-freflection"
+cmake --build build -j 4
+```
+
+The individual parts:
+
+* `-DREFLECTCPP_USE_CPP26_REFLECTION=ON` switches reflect-cpp to the C++-26 reflection
+  implementation and defines the macro `REFLECTCPP_USE_CPP26_REFLECTION`. If
+  `CMAKE_CXX_STANDARD` is not set, it will be set to 26 automatically.
+* `-DCMAKE_CXX_STANDARD=26` sets the C++ standard to 26.
+* `-DCMAKE_CXX_FLAGS="-freflection"` activates the C++ reflection facilities in the
+  compiler itself. Use `-freflection-latest` on Clang instead.
+
+When compiling with C++-26 reflection, the option `REFLECTCPP_USE_STD_EXPECTED` is
+enabled by default as well, which means that `rfl::Result<T>` is an alias for
+`std::expected<T, rfl::Error>`. If you want to keep using the built-in `rfl::Result`
+type, pass `-DREFLECTCPP_USE_STD_EXPECTED=OFF`.
+
+If you include the source files directly into your own build (see
+[Installation](install.md#option-4-include-source-files-into-your-own-build)), add the
+compile definition `-DREFLECTCPP_USE_CPP26_REFLECTION` and the appropriate compiler flag
+to all translation units that include reflect-cpp.
+
+## What C++-26 reflection changes
+
+### C arrays and inheritance are supported out of the box
+
+In C++-20/23 mode, fixed-size C arrays and inheritance are only supported when you pass
+the flag `-DREFLECT_CPP_C_ARRAYS_OR_INHERITANCE`, and inheritance only works when all of
+the fields are inside the same struct. Refer to
+[C arrays and inheritance](c_arrays_and_inheritance.md) for details.
+
+In C++-26 mode, neither restriction applies:
+
+* Fixed-size C arrays are regular fields as far as the compiler's reflection is concerned,
+  so they work without any flag.
+* The fields of base classes are combined with the fields of the derived class, so the
+  fields may be spread out over multiple structs.
+
+For example, this is not supported in C++-20/23 mode, but works as-is in C++-26 mode:
+
+```cpp
+struct Base {
+  int x;
+};
+
+struct Derived : Base {
+  int y;
+};
+
+const auto derived = Derived{1, 2};
+
+rfl::json::write(derived);
+```
+
+This results in the following JSON string:
+
+```json
+{"x":1,"y":2}
+```
+
+### No range restrictions for enums
+
+In C++-20/23 mode, enum values must be in the range `[RFL_ENUM_RANGE_MIN,
+RFL_ENUM_RANGE_MAX]`, where the default range is `[-256, 256]`. Refer to
+[Enums](enums.md) for details.
+
+In C++-26 mode, the enumerators are read directly from the compiler, so there is no
+restriction on the range of enum values, and `RFL_ENUM_RANGE_MIN` and `RFL_ENUM_RANGE_MAX`
+are not needed.
+
+### Lower compile-time cost
+
+In C++-20/23 mode, reflect-cpp infers the fields of a struct by figuring out how the
+struct can be constructed. This requires a lot of compile-time work, especially in the
+presence of C arrays and inheritance. In C++-26 mode, the fields and enumerators are
+queried directly from the compiler's reflection information, which is considerably
+cheaper.
+
+## Summary
+
+| Feature | C++-20/23 | C++-26 |
+|---------|-----------|--------|
+| Supported compilers | GCC 11.4+, Clang 14.0+, MSVC 17.8+ | GCC 16.2+ (Clang: experimental) |
+| Compiler flag | *(none)* | `-freflection` (GCC), `-freflection-latest` (Clang) |
+| CMake option | *(none)* | `-DREFLECTCPP_USE_CPP26_REFLECTION=ON` |
+| Fixed-size C arrays | requires `-DREFLECT_CPP_C_ARRAYS_OR_INHERITANCE` | supported out of the box |
+| Inheritance | requires `-DREFLECT_CPP_C_ARRAYS_OR_INHERITANCE`, fields must be in a single struct | supported out of the box, fields may be spread over multiple structs |
+| Enum value range | restricted to `[RFL_ENUM_RANGE_MIN, RFL_ENUM_RANGE_MAX]` (default `[-256, 256]`) | no restriction |
+| `rfl::Result` | built-in type (or `std::expected` via `-DREFLECTCPP_USE_STD_EXPECTED`) | `std::expected` by default |
+| Compile time | higher | lower |

docs/enums.md

@@ -46,6 +46,13 @@ However, some limitations apply:
 2. Enum values must be in the range `[RFL_ENUM_RANGE_MIN, RFL_ENUM_RANGE_MAX]`. If the range is not specified, the
    default range is `[-256, 256]`.
 
+    !!! note "C++-26 reflection"
+
+        This restriction only applies when compiling reflect-cpp with C++-20 or C++-23. When
+        compiling with [C++-26 reflection](cpp26_reflection.md), the enumerators are read
+        directly from the compiler, so there is no restriction on the range of enum values,
+        and `RFL_ENUM_RANGE_MIN` and `RFL_ENUM_RANGE_MAX` are not needed.
+
     - You can specify a custom range for the all enum values by defining `RFL_ENUM_RANGE_MIN` and `RFL_ENUM_RANGE_MAX`
       before including the reflect-cpp header:
 

docs/install.md

@@ -5,13 +5,44 @@ hide:
 
 # Installation
 
-The following compilers are supported:
+The following compilers are supported for C++-20:
 - GCC 11.4 or higher
 - Clang 14.0 or higher
 - MSVC 17.8 (19.38) or higher
 
+The following compilers are supported for C++-26:
+- GCC 16.2 or higher
+
 You can include the source files into your build or compile it using cmake and vcpkg.
 
+## Compiling with C++-26 reflection
+
+By default, reflect-cpp uses a C++-20 compatible reflection implementation, which works
+across a wide range of compilers. If you want to use the standard C++ reflection
+facilities (`<meta>`, [P2996](https://wg21.link/P2996)), you can compile reflect-cpp in
+C++-26 mode instead. This is more powerful: fixed-size C arrays and inheritance are
+supported out of the box, and there are no range restrictions for enums. Refer to
+[C++26 reflection](cpp26_reflection.md) for details.
+
+To enable C++-26 reflection, pass the CMake option `REFLECTCPP_USE_CPP26_REFLECTION` and
+the compiler flag that activates reflection support in your compiler:
+
+* GCC: `-freflection`
+* Clang: `-freflection-latest` (experimental, only available in Clang builds that
+  implement [P2996](https://wg21.link/P2996), such as Bloomberg's
+  [clang-p2996](https://github.com/bloomberg/clang-p2996) fork)
+
+For example, using cmake:
+
+```bash
+cmake -S . -B build -DCMAKE_CXX_STANDARD=26 -DCMAKE_BUILD_TYPE=Release -DREFLECTCPP_USE_CPP26_REFLECTION=ON -DCMAKE_CXX_FLAGS="-freflection"
+cmake --build build -j 4
+```
+
+If you include the source files into your own build (see Option 4 below), also add the
+compile definition `-DREFLECTCPP_USE_CPP26_REFLECTION` and the appropriate compiler flag
+to all translation units that include reflect-cpp.
+
 ## Option 1: Using vcpkg
 
 Refer to [this port](https://vcpkg.link/ports/reflectcpp):

mkdocs.yaml

@@ -112,6 +112,7 @@ nav:
       - Custom Format: supported_formats/supporting_your_own_format.md
   # - Reflective Programming: ./reflective_programming.md
   - Installation: install.md
+  - C++26 reflection: cpp26_reflection.md
   - Documentation:
     - docs-readme.md
     - The basics: