[gcc r17-249] libstdc++: Tweak Doxygen comments for experimental simd

[Jonathan Wakely]

https://gcc.gnu.org/g:bbe8fff16e366976bd95b981c138e5f12caf9010

commit r17-249-gbbe8fff16e366976bd95b981c138e5f12caf9010
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Fri May 1 10:58:57 2026 +0100

    libstdc++: Tweak Doxygen comments for experimental simd
    
    I noticed that Doxygen was not documenting the contents of
    <experimental/simd> 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 <experimental/simd> namespace.
            * include/experimental/bits/simd.h: Move BEGIN macro before
            Doxygen @{ group.

Diff:
---
 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 fc82debd1b4b..9393d5dfb437 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 8c30c8af2688..ce0867fd8eb8 100644
--- a/libstdc++-v3/include/experimental/bits/simd.h
+++ b/libstdc++-v3/include/experimental/bits/simd.h
@@ -55,6 +55,11 @@
 #include <arm_sve.h>
 #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;