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 49712fa7e31cca545f1c0fefdfbaacd207792bcf..aeeb664044183c01ad878e6f9205bfcceea5aff4 100644 (file)
--- 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 (file)
index 0000000..5110f8b
--- /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