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

[Tomasz Kaminski]

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:
>> + *  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
> >>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://gcc.gnu.org/pipermail/libstdc++/attachments/20260402/530b2302/attachment.htm>