[PATCH 10/10] libstdc++: Add Doxygen documentation to <version>

[Jonathan Wakely]

libstdc++-v3/ChangeLog:

	* include/std/version: Add Doxygen documentation comment.
---

Tested x86_64-linux, docs built with Doxygen 1.13.2 and 1.17.0 (from git)

 libstdc++-v3/include/std/version | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/libstdc++-v3/include/std/version b/libstdc++-v3/include/std/version
index c6ac031f6b54..7b2273a245d8 100644
--- a/libstdc++-v3/include/std/version
+++ b/libstdc++-v3/include/std/version
@@ -25,6 +25,32 @@
 /** @file version
  *  This is a Standard C++ Library file.  You should @c \#include this file
  *  in your programs, rather than any of the @a *.h implementation files.
+ *
+ *  The `<version>` header defines feature test macros that can be used to
+ *  programmatically test properties of the C++ implementation you are using.
+ *  For example, by including `<version>` and then checking whether the
+ *  `__cpp_lib_expected` macro is defined, you can tell whether `std::expected`
+ *  is supported. The macros that are defined by `<version>` and the values
+ *  of those macros depend on the C++ Standard Library implementation and on
+ *  compiler flags such as `-std=c++23`, `-ffreestanding`, and `-fno-rtti`.
+ *
+ *  The list of macros that should be defined by `<version>` header can be
+ *  found in the C++ standard committee's SD-6 document:
+ *  https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations
+ *  That document also documents which standard proposals the different macro
+ *  values correspond to, e.g. `__cpp_lib_expected == 202202L` implies that
+ *  only the original feature set of `std::expected` is supported, and
+ *  `__cpp_lib_expected == 202211L` implies that the additional monadic
+ *  functions such as `std::expected::and_then` are also supported.
+ *
+ *  The `<version>` header should also define any implementation-specific
+ *  macros, which can sometimes be used to tell which C++ implementation
+ *  the code is being compiled with. For example, in libstdc++ `<version>`
+ *  defines the `_GLIBCXX_RELEASE` macro. Testing for the
+ *
+ *  The `<version>` header was first defined in C++20, but libstdc++
+ *  provides it unconditionally and many of the macros it defines are
+ *  present (and meaningful) for C++17 and older standards.
  */
 
 #ifndef _GLIBCXX_VERSION_INCLUDED
-- 
2.53.0