From bbe8fff16e366976bd95b981c138e5f12caf9010 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Fri, 1 May 2026 10:58:57 +0100 Subject: [PATCH] libstdc++: Tweak Doxygen comments for experimental simd I noticed that Doxygen was not documenting the contents of as part of namespace std, because it didn't know about the _GLIBCXX_SIMD_BEGIN_NAMESPACE and _GLIBCXX_SIMD_END_NAMESPACE macros which open and close namespace std::experimental::parallelism_v2. After defining those macros in the Doxygen config, the Doxygen comments in experimental/bits/simd.h were causing namespace std to be documented as part of the Parallelism TS v2. That's because the preprocessed code looks like: /** @ingroup ts_simd * @{ */ namespace std::experimental::inline parallelism_v2 { This causes Doxygen to apply the @ingroup command to all three of namespace std, namespace std::experimental, and namespace std::experimental::parallelism_v2. I don't know if this is the intended behaviour, but it doesn't seem useful so I've opened an issue about it: https://github.com/doxygen/doxygen/issues/12114 To workaround this, we can move the _GLIBCXX_SIMD_BEGIN_NAMESPACE macro before the @{ group and document it separately with a @namespace comment. That makes the @ingroup only apply to the namespace named by the @namespace command, not to its enclosing namespaces as well. Moving the position of the BEGIN macro also fixes the nesting, as previously we had @{ then BEGIN then @} then END. Now we have BEGIN @{ @} END which seems preferable. libstdc++-v3/ChangeLog: * doc/doxygen/user.cfg.in (PREDEFINED): Add BEGIN/END macros for the namespace. * include/experimental/bits/simd.h: Move BEGIN macro before Doxygen @{ group. --- libstdc++-v3/doc/doxygen/user.cfg.in | 2 ++ libstdc++-v3/include/experimental/bits/simd.h | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index fc82debd1b4..9393d5dfb43 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -2912,6 +2912,8 @@ PREDEFINED = __cplusplus=202603L \ _GLIBCXX_HAVE_ICONV=1 \ "_GLIBCXX_DOXYGEN_ONLY(X)=X " \ __exception_ptr=__unspecified__ \ + "_GLIBCXX_SIMD_BEGIN_NAMESPACE=namespace std::experimental::inline parallelism_v2 {" \ + "_GLIBCXX_SIMD_END_NAMESPACE=}" \ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this diff --git a/libstdc++-v3/include/experimental/bits/simd.h b/libstdc++-v3/include/experimental/bits/simd.h index 8c30c8af268..ce0867fd8eb 100644 --- a/libstdc++-v3/include/experimental/bits/simd.h +++ b/libstdc++-v3/include/experimental/bits/simd.h @@ -55,6 +55,11 @@ #include #endif +/** @namespace std::experimental::parallelism_v2 + * @ingroup ts_simd + */ +_GLIBCXX_SIMD_BEGIN_NAMESPACE + /** @ingroup ts_simd * @{ */ @@ -78,7 +83,6 @@ * Variable names: * __k: mask object (vector- or bitmask) */ -_GLIBCXX_SIMD_BEGIN_NAMESPACE #if !_GLIBCXX_SIMD_X86INTRIN using __m128 [[__gnu__::__vector_size__(16)]] = float;