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 --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index fc82debd1b4b0f6bb2607a0ce0488985d72445ea..9393d5dfb4372d8ebfe45128e05a769b60c4293b 100644 (file)
--- 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 8c30c8af268812c834e613d7291385d1f9b5ad41..ce0867fd8eb8d6340fd712920878591c961e022d 100644 (file)
--- 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;