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

[Jonathan Wakely]

On Thu, 2 Apr 2026 at 09:18, Tomasz Kaminski <tkaminsk@redhat.com> wrote:
>
>
>
> On Thu, Apr 2, 2026 at 12:02 AM Jonathan Wakely <jwakely@redhat.com> wrote:
>>
>> 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 remainder of last sentence is incomplete.

Oops, yes. I meant to write something like this and hadn't decided how
to word it.

--- a/libstdc++-v3/include/std/version
+++ b/libstdc++-v3/include/std/version
@@ -46,7 +46,10 @@
 *  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
+ *  defines the `_GLIBCXX_RELEASE` macro. Testing for supported features
+ *  using the standard feature test macros is recommended instead of writing
+ *  custom checks for specific implementations and specific versions using
+ *  non-standard macros.
 *
 *  The `<version>` header was first defined in C++20, but libstdc++
 *  provides it unconditionally and many of the macros it defines are






>>
>> + *
>> + *  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
>>