From: Jonathan Wakely <jwakely@redhat.com>
Date: Fri, 17 Nov 2023 12:52:45 +0000 (+0000)
Subject: libstdc++: Add more Doxygen comments and another test for std::out_ptr
X-Git-Tag: basepoints/gcc-15~4580
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=66c15287ddbdc9c270fca528bb641d265a370dcc;p=thirdparty%2Fgcc.git

libstdc++: Add more Doxygen comments and another test for std::out_ptr

Improve Doxygen comments for std::out_ptr etc. and add a test for the
feature test macro.  Also remove a redundant preprocessor condition.

Ideally the docs for std::out_ptr and std::inout_ptr would show examples
of how to use them and what they do, but that would take some effort.
I'll aim to do that before GCC 14 is released.

libstdc++-v3/ChangeLog:

	* include/bits/out_ptr.h: Add Doxygen comments. Remove a
	redundant preprocessor condition.
	* testsuite/20_util/smartptr.adapt/version.cc: New test.
---

diff --git a/libstdc++-v3/include/bits/out_ptr.h b/libstdc++-v3/include/bits/out_ptr.h
index 49712fa7e31c..aeeb66404418 100644
--- a/libstdc++-v3/include/bits/out_ptr.h
+++ b/libstdc++-v3/include/bits/out_ptr.h
@@ -43,8 +43,14 @@ namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
-#ifdef __glibcxx_out_ptr // C++ >= 23
-  /// Adapt a smart pointer for functions taking an output pointer parameter.
+  /// Smart pointer adaptor for functions taking an output pointer parameter.
+  /**
+   * @tparam _Smart The type of pointer to adapt.
+   * @tparam _Pointer The type of pointer to convert to.
+   * @tparam _Args... Argument types used when resetting the smart pointer.
+   * @since C++23
+   * @headerfile <memory>
+   */
   template<typename _Smart, typename _Pointer, typename... _Args>
     class out_ptr_t
     {
@@ -276,7 +282,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       template<typename, typename, typename...> friend class inout_ptr_t;
     };
 
-  /// Adapt a smart pointer for functions taking an output pointer parameter.
+  /// Smart pointer adaptor for functions taking an inout pointer parameter.
+  /**
+   * @tparam _Smart The type of pointer to adapt.
+   * @tparam _Pointer The type of pointer to convert to.
+   * @tparam _Args... Argument types used when resetting the smart pointer.
+   * @since C++23
+   * @headerfile <memory>
+   */
   template<typename _Smart, typename _Pointer, typename... _Args>
     class inout_ptr_t
     {
@@ -367,6 +380,15 @@ namespace __detail
 }
 /// @endcond
 
+  /// Adapt a smart pointer for functions taking an output pointer parameter.
+  /**
+   * @tparam _Pointer The type of pointer to convert to.
+   * @param __s The pointer that should take ownership of the result.
+   * @param __args... Arguments to use when resetting the smart pointer.
+   * @return A std::inout_ptr_t referring to `__s`.
+   * @since C++23
+   * @headerfile <memory>
+   */
   template<typename _Pointer = void, typename _Smart, typename... _Args>
     inline auto
     out_ptr(_Smart& __s, _Args&&... __args)
@@ -379,6 +401,15 @@ namespace __detail
       return _Ret(__s, std::forward<_Args>(__args)...);
     }
 
+  /// Adapt a smart pointer for functions taking an inout pointer parameter.
+  /**
+   * @tparam _Pointer The type of pointer to convert to.
+   * @param __s The pointer that should take ownership of the result.
+   * @param __args... Arguments to use when resetting the smart pointer.
+   * @return A std::inout_ptr_t referring to `__s`.
+   * @since C++23
+   * @headerfile <memory>
+   */
   template<typename _Pointer = void, typename _Smart, typename... _Args>
     inline auto
     inout_ptr(_Smart& __s, _Args&&... __args)
@@ -391,6 +422,7 @@ namespace __detail
       return _Ret(__s, std::forward<_Args>(__args)...);
     }
 
+  /// @cond undocumented
   template<typename _Smart, typename _Pointer, typename... _Args>
   template<typename _Smart2, typename _Pointer2, typename... _Args2>
     inline
@@ -422,11 +454,10 @@ namespace __detail
       else
 	__reset();
     }
-#endif // __glibcxx_out_ptr
+  /// @endcond
 
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace
 
 #endif // __glibcxx_out_ptr
 #endif /* _GLIBCXX_OUT_PTR_H */
-
diff --git a/libstdc++-v3/testsuite/20_util/smartptr.adapt/version.cc b/libstdc++-v3/testsuite/20_util/smartptr.adapt/version.cc
new file mode 100644
index 000000000000..5110f8b371e1
--- /dev/null
+++ b/libstdc++-v3/testsuite/20_util/smartptr.adapt/version.cc
@@ -0,0 +1,19 @@
+// { dg-do preprocess { target c++23 } }
+// { dg-add-options no_pch }
+
+#include <memory>
+
+#ifndef __cpp_lib_out_ptr
+# error "Feature test macro for out_ptr is missing in <memory>"
+#elif __cpp_lib_out_ptr < 202106L
+# error "Feature test macro for out_ptr has wrong value in <memory>"
+#endif
+
+#undef __cpp_lib_out_ptr
+#include <version>
+
+#ifndef __cpp_lib_out_ptr
+# error "Feature test macro for out_ptr is missing in <version>"
+#elif __cpp_lib_out_ptr < 202106L
+# error "Feature test macro for out_ptr has wrong value in <version>"
+#endif