[gcc r12-4622] libstdc++: Add Doxygen comments to contents of <functional>

[gcc r12-4622] libstdc++: Add Doxygen comments to contents of <functional>

[Jonathan Wakely]

https://gcc.gnu.org/g:5a5d7c2c802f005f8cf85e0bfb7a77cf13203dae

commit r12-4622-g5a5d7c2c802f005f8cf85e0bfb7a77cf13203dae
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Oct 21 17:44:47 2021 +0100

    libstdc++: Add Doxygen comments to contents of <functional>
    
    libstdc++-v3/ChangeLog:
    
            * include/bits/mofunc_impl.h: Add doxygen comments.
            * include/std/functional: Likewise.

Diff:
---
 libstdc++-v3/include/bits/mofunc_impl.h | 37 +++++++++++++
 libstdc++-v3/include/std/functional     | 94 ++++++++++++++++++++++++++++-----
 2 files changed, 119 insertions(+), 12 deletions(-)

diff --git a/libstdc++-v3/include/bits/mofunc_impl.h b/libstdc++-v3/include/bits/mofunc_impl.h
index 968d235f867..6cc9711a42b 100644
--- a/libstdc++-v3/include/bits/mofunc_impl.h
+++ b/libstdc++-v3/include/bits/mofunc_impl.h
@@ -44,6 +44,22 @@ namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
+  /**
+   *  @brief Polymorphic function wrapper.
+   *  @ingroup functors
+   *  @since C++23
+   *  @headername functional
+   *
+   *  The `std::move_only_function` class template is a call wrapper similar
+   *  to *  `std::function`, but does not require the stored target function
+   *  to be copyable.
+   *
+   *  It also supports const-qualification, ref-qualification, and
+   *  no-throw guarantees. The qualifications and exception-specification
+   *  of the `move_only_function::operator()` member function are respected
+   *  when invoking the target function.
+   *
+   */
   template<typename _Res, typename... _ArgTypes, bool _Noex>
     class move_only_function<_Res(_ArgTypes...) _GLIBCXX_MOF_CV
 			       _GLIBCXX_MOF_REF noexcept(_Noex)>
@@ -64,15 +80,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     public:
       using result_type = _Res;
 
+      /// Creates an empty object.
       move_only_function() noexcept { }
 
+      /// Creates an empty object.
       move_only_function(nullptr_t) noexcept { }
 
+      /// Moves the target object, leaving the source empty.
       move_only_function(move_only_function&& __x) noexcept
       : _Mofunc_base(static_cast<_Mofunc_base&&>(__x)),
 	_M_invoke(std::__exchange(__x._M_invoke, nullptr))
       { }
 
+      /// Stores a target object initialized from the argument.
       template<typename _Fn, typename _Vt = decay_t<_Fn>>
 	requires (!is_same_v<_Vt, move_only_function>)
 	  && (!__is_in_place_type_v<_Vt>) && __is_callable_from<_Vt>
@@ -89,6 +109,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	  _M_invoke = &_S_invoke<_Vt>;
 	}
 
+      /// Stores a target object initialized from the arguments.
       template<typename _Tp, typename... _Args>
 	requires is_constructible_v<_Tp, _Args...>
 	  && __is_callable_from<_Tp>
@@ -101,6 +122,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	  _M_init<_Tp>(std::forward<_Args>(__args)...);
 	}
 
+      /// Stores a target object initialized from the arguments.
       template<typename _Tp, typename _Up, typename... _Args>
 	requires is_constructible_v<_Tp, initializer_list<_Up>&, _Args...>
 	  && __is_callable_from<_Tp>
@@ -114,6 +136,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	  _M_init<_Tp>(__il, std::forward<_Args>(__args)...);
 	}
 
+      /// Stores a new target object, leaving `x` empty.
       move_only_function&
       operator=(move_only_function&& __x) noexcept
       {
@@ -122,6 +145,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	return *this;
       }
 
+      /// Destroys the target object (if any).
       move_only_function&
       operator=(nullptr_t) noexcept
       {
@@ -130,6 +154,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	return *this;
       }
 
+      /// Stores a new target object, initialized from the argument.
       template<typename _Fn>
 	requires is_constructible_v<move_only_function, _Fn>
 	move_only_function&
@@ -142,8 +167,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
       ~move_only_function() = default;
 
+      /// True if a target object is present, false otherwise.
       explicit operator bool() const noexcept { return _M_invoke != nullptr; }
 
+      /** Invoke the target object.
+       *
+       * The target object will be invoked using the supplied arguments,
+       * and as an lvalue or rvalue, and as const or non-const, as dictated
+       * by the template arguments of the `move_only_function` specialization.
+       *
+       * @pre Must not be empty.
+       */
       _Res
       operator()(_ArgTypes... __args) _GLIBCXX_MOF_CV_REF noexcept(_Noex)
       {
@@ -151,6 +185,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	return _M_invoke(this, std::forward<_ArgTypes>(__args)...);
       }
 
+      /// Exchange the target objects (if any).
       void
       swap(move_only_function& __x) noexcept
       {
@@ -158,10 +193,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	std::swap(_M_invoke, __x._M_invoke);
       }
 
+      /// Exchange the target objects (if any).
       friend void
       swap(move_only_function& __x, move_only_function& __y) noexcept
       { __x.swap(__y); }
 
+      /// Check for emptiness by comparing with `nullptr`.
       friend bool
       operator==(const move_only_function& __x, nullptr_t) noexcept
       { return __x._M_invoke == nullptr; }
diff --git a/libstdc++-v3/include/std/functional b/libstdc++-v3/include/std/functional
index 2db1c05349b..5cf4417b963 100644
--- a/libstdc++-v3/include/std/functional
+++ b/libstdc++-v3/include/std/functional
@@ -79,6 +79,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /** @brief The type of placeholder objects defined by libstdc++.
    *  @ingroup binders
+   *  @since C++11
    */
   template<int _Num> struct _Placeholder { };
 
@@ -90,7 +91,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #  define __cpp_lib_constexpr_functional 201907L
 # endif
 
-  /// Invoke a callable object.
+  /** Invoke a callable object.
+   *
+   * `std::invoke` takes a callable object as its first argument and calls it
+   * with the remaining arguments. The callable object can be a pointer or
+   * reference to a function, a lambda closure, a class with `operator()`,
+   * or even a pointer-to-member.  For a pointer-to-member the first argument
+   * must be a reference or pointer to the object that the pointer-to-member
+   * will be applied to.
+   *
+   *  @since C++17
+   */
   template<typename _Callable, typename... _Args>
     inline _GLIBCXX20_CONSTEXPR invoke_result_t<_Callable, _Args...>
     invoke(_Callable&& __fn, _Args&&... __args)
@@ -103,7 +114,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #if __cplusplus > 202002L
 # define __cpp_lib_invoke_r 202106L
 
-  /// Invoke a callable object and convert the result to _Res.
+  /** Invoke a callable object and convert the result to `_Res`.
+   *
+   * `std::invoke_r<R>(f, args...)` is equivalent to `std::invoke(f, args...)`
+   * with the result implicitly converted to `R`.
+   *
+   *  @since C++23
+   */
   template<typename _Res, typename _Callable, typename... _Args>
     requires is_invocable_r_v<_Res, _Callable, _Args...>
     constexpr _Res
@@ -116,6 +133,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // C++23
 #endif // C++17
 
+  /// @cond undocumented
+
   template<typename _MemFunPtr,
 	   bool __is_mem_fn = is_member_function_pointer<_MemFunPtr>::value>
     class _Mem_fn_base
@@ -182,13 +201,32 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     {
       using _Mem_fn_base<_Res _Class::*>::_Mem_fn_base;
     };
+  /// @endcond
 
   // _GLIBCXX_RESOLVE_LIB_DEFECTS
   // 2048.  Unnecessary mem_fn overloads
   /**
-   *  @brief Returns a function object that forwards to the member
-   *  pointer @a pm.
-   *  @ingroup functors
+   * @brief Returns a function object that forwards to the member pointer
+   * pointer `pm`.
+   *
+   * This allows a pointer-to-member to be transformed into a function object
+   * that can be called with an object expression as its first argument.
+   *
+   * For a pointer-to-data-member the result must be called with exactly one
+   * argument, the object expression that would be used as the first operand
+   * in a `obj.*memptr` or `objp->*memptr` expression.
+   *
+   * For a pointer-to-member-function the result must be called with an object
+   * expression and any additional arguments to pass to the member function,
+   * as in an expression like `(obj.*memfun)(args...)` or
+   * `(objp->*memfun)(args...)`.
+   *
+   * The object expression can be a pointer, reference, `reference_wrapper`,
+   * or smart pointer, and the call wrapper will dereference it as needed
+   * to apply the pointer-to-member.
+   *
+   * @ingroup functors
+   * @since C++11
    */
   template<typename _Tp, typename _Class>
     _GLIBCXX20_CONSTEXPR
@@ -199,12 +237,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     }
 
   /**
-   *  @brief Determines if the given type _Tp is a function object that
-   *  should be treated as a subexpression when evaluating calls to
-   *  function objects returned by bind().
+   * @brief Trait that identifies a bind expression.
+   * 
+   * Determines if the given type `_Tp` is a function object that
+   * should be treated as a subexpression when evaluating calls to
+   * function objects returned by `std::bind`.
    *
-   *  C++11 [func.bind.isbind].
-   *  @ingroup binders
+   * C++11 [func.bind.isbind].
+   * @ingroup binders
+   * @since C++11
    */
   template<typename _Tp>
     struct is_bind_expression
@@ -216,6 +257,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *
    *  C++11 [func.bind.isplace].
    *  @ingroup binders
+   *  @since C++11
    */
   template<typename _Tp>
     struct is_placeholder
@@ -232,6 +274,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /** @namespace std::placeholders
    *  @brief ISO C++ 2011 namespace for std::bind placeholders.
    *  @ingroup binders
+   *  @since C++11
    */
   namespace placeholders
   {
@@ -274,6 +317,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  Partial specialization of is_placeholder that provides the placeholder
    *  number for the placeholder objects defined by libstdc++.
    *  @ingroup binders
+   *  @since C++11
    */
   template<int _Num>
     struct is_placeholder<_Placeholder<_Num> >
@@ -285,6 +329,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     : public integral_constant<int, _Num>
     { };
 
+  /// @cond undocumented
 
   // Like tuple_element_t but SFINAE-friendly.
   template<std::size_t __i, typename _Tuple>
@@ -414,6 +459,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     -> __tuple_element_t<_Ind, tuple<_Tp...>> const volatile&
     { return std::get<_Ind>(const_cast<const tuple<_Tp...>&>(__tuple)); }
 
+  /// @endcond
+
   /// Type of the function object returned from bind().
   template<typename _Signature>
     class _Bind;
@@ -799,6 +846,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief Function template for std::bind.
    *  @ingroup binders
+   *  @since C++11
    */
   template<typename _Func, typename... _BoundArgs>
     inline _GLIBCXX20_CONSTEXPR typename
@@ -823,6 +871,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief Function template for std::bind<R>.
    *  @ingroup binders
+   *  @since C++11
    */
   template<typename _Result, typename _Func, typename... _BoundArgs>
     inline _GLIBCXX20_CONSTEXPR
@@ -923,6 +972,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     using _Bind_front_t
       = _Bind_front<decay_t<_Fn>, decay_t<_Args>...>;
 
+  /** Create call wrapper by partial application of arguments to function.
+   *
+   * The result of `std::bind_front(f, args...)` is a function object that
+   * stores `f` and the bound arguments, `args...`. When that function
+   * object is invoked with `call_args...` it returns the result of calling
+   * `f(args..., call_args...)`.
+   *
+   *  @since C++20
+   */
   template<typename _Fn, typename... _Args>
     constexpr _Bind_front_t<_Fn, _Args...>
     bind_front(_Fn&& __fn, _Args&&... __args)
@@ -932,7 +990,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       return _Bind_front_t<_Fn, _Args...>(0, std::forward<_Fn>(__fn),
 					  std::forward<_Args>(__args)...);
     }
-#endif
+#endif // C++20
 
 #if __cplusplus >= 201402L
   /// Generalized negator.
@@ -1003,8 +1061,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct __is_byte_like<byte, equal_to<void>>
     : true_type { };
 
+  // [func.not_fn] Function template not_fn
 #define __cpp_lib_not_fn 201603
-  /// [func.not_fn] Function template not_fn
+  /** Wrap a function object to create one that negates its result.
+   *
+   * The function template `std::not_fn` creates a "forwarding call wrapper",
+   * which is a function object that wraps another function object and
+   * when called, forwards its arguments to the wrapped function object.
+   *
+   * The result of invoking the wrapper is the negation (using `!`) of
+   * the wrapped function object.
+   *
+   *  @ingroup functors
+   *  @since C++17
+   */
   template<typename _Fn>
     _GLIBCXX20_CONSTEXPR
     inline auto