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

[Jonathan Wakely]

On Thu, 2 Apr 2026 at 11:51, Tomasz Kaminski <tkaminsk@redhat.com> wrote:
>
>
>
> On Thu, Apr 2, 2026 at 12:34 PM Jonathan Wakely <jwakely@redhat.com> wrote:
>>
>> 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.
>
> Looks good, but should be in separate paragraph from implementation-specific
> macros. I would put the sentence after end of second paragraph, i.e one starting
> from:

Hmm, I wanted to say "don't use the impl-specific ones" in the same
paragraph as talking about those ones.

> >> + *  The `<version>` header defines feature test macros that can be used to
> >> + *  programmatically test properties
>>
>>  *
>>  *  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
>> >>
>>