Add/fix Public API documentation

docs/sphinx/api/public_api.rst

@@ -462,8 +462,8 @@ Classes
    :cpp:class:`hpx::function`                     :cppreference-generic:`utility/functional,function`
    :cpp:class:`hpx::function_ref`                 |p0792|_
    :cpp:class:`hpx::move_only_function`           :cppreference-generic:`utility/functional,move_only_function`
-   :cpp:struct:`hpx::traits::is_bind_expression`  :cppreference-generic:`utility/functional,is_bind_expression`
-   :cpp:struct:`hpx::traits::is_placeholder`      :cppreference-generic:`utility/functional,is_placeholder`
+   :cpp:struct:`hpx::is_bind_expression`          :cppreference-generic:`utility/functional,is_bind_expression`
+   :cpp:struct:`hpx::is_placeholder`              :cppreference-generic:`utility/functional,is_placeholder`
    :cpp:struct:`hpx::scoped_annotation`
    =============================================  =============================================================
 
@@ -477,7 +477,7 @@ Functions
    ========================================  =====================================================
    :cpp:func:`hpx::annotated_function`
    :cpp:func:`hpx::bind`                     :cppreference-generic:`utility/functional,bind`
-   :cpp:func:`hpx::experimental::bind_back`
+   :cpp:func:`hpx::bind_back`                :cppreference-generic:`utility/functional,bind_front`
    :cpp:func:`hpx::bind_front`               :cppreference-generic:`utility/functional,bind_front`
    :cpp:func:`hpx::invoke`                   :cppreference-generic:`utility/functional,invoke`
    :cpp:func:`hpx::invoke_fused`             :cppreference-generic:`utility,apply`

libs/core/functional/include/hpx/functional/bind_back.hpp

@@ -5,6 +5,8 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file bind_back.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -152,6 +154,18 @@ namespace hpx {
         };
     }    // namespace detail
 
+    /// \brief Function templates \c bind_back generate a forwarding call wrapper
+    ///        for \c f. Calling this wrapper is equivalent to invoking \c f with its
+    ///        last \c sizeof...(Ts) parameters bound to \c vs.
+    ///
+    /// \param f    Callable object (function object, pointer to function,
+    ///             reference to function, pointer to member function, or pointer
+    ///             to data member) that will be bound to some arguments
+    /// \param vs   list of the arguments to bind to the last \c sizeof...(Ts)
+    ///             parameters of \c f
+    /// \returns    A function object of type \c T that is unspecified, except that
+    ///             the types of objects returned by two calls to \c hpx::bind_back
+    ///             with the same arguments are the same.
     template <typename F, typename... Ts>
     constexpr hpx::detail::bound_back<std::decay_t<F>,
         util::make_index_pack_t<sizeof...(Ts)>, util::decay_unwrap_t<Ts>...>

libs/core/functional/include/hpx/functional/bind_front.hpp

@@ -156,17 +156,17 @@ namespace hpx {
         };
     }    // namespace detail
 
-    /// Function template \a bind_front generates a forwarding call wrapper for \a f.
-    /// Calling this wrapper is equivalent to invoking \a f with its (1) first or
-    /// (2) last \a sizeof...(Ts) parameters bound to \a vs.
+    /// \brief Function template \c bind_front generates a forwarding call wrapper
+    ///        for \c f. Calling this wrapper is equivalent to invoking \c f with its
+    ///        first \c sizeof...(Ts) parameters bound to \c vs.
     ///
     /// \param f    Callable object (function object, pointer to function,
     ///             reference to function, pointer to member function, or pointer
     ///             to data member) that will be bound to some arguments
-    /// \param vs   list of the arguments to bind to the (1) first or
-    ///             (2) last \a sizeof...(Ts) parameters of f
-    /// \returns    A function object of type \a T that is unspecified, except that
-    ///             the types of objects returned by two calls to \a hpx::bind_front
+    /// \param vs   list of the arguments to bind to the first or \c sizeof...(Ts)
+    ///             parameters of \c f
+    /// \returns    A function object of type \c T that is unspecified, except that
+    ///             the types of objects returned by two calls to \c hpx::bind_front
     ///             with the same arguments are the same.
     template <typename F, typename... Ts>
     constexpr detail::bound_front<std::decay_t<F>,

libs/core/functional/include/hpx/functional/traits/is_bind_expression.hpp

@@ -14,16 +14,18 @@
 
 namespace hpx {
 
-    /// If T is the type produced by a call to std::bind, this template is
-    /// derived from std::true_type. For any other type, this template is
-    /// derived from std::false_type.
+    /// \brief If \c T is the type produced by a call to \c hpx::bind, this
+    ///        template is derived from \c std::true_type. For any other type,
+    ///        this template is derived from \c std::false_type.
     ///
-    /// This template may be specialized for a user-defined type T to implement
-    /// UnaryTypeTrait with base characteristic of std::true_type to indicate
-    /// that T should be treated by std::bind as if it were the type of a bind
-    /// subexpression: when a bind-generated function object is invoked, a bound
-    /// argument of this type will be invoked as a function object and will be
-    /// given all the unbound arguments passed to the bind-generated object.
+    /// \details This template may be specialized for a user-defined type \c T
+    ///          to implement \a UnaryTypeTrait with base characteristic of
+    ///          \c std::true_type to indicate that \c T should be treated by
+    ///          \c hpx::bind as if it were the type of a bind subexpression:
+    ///          when a bind-generated function object is invoked, a bound
+    ///          argument of this type will be invoked as a function object and
+    ///          will be given all the unbound arguments passed to the
+    ///          bind-generated object.
     template <typename T>
     struct is_bind_expression : std::is_bind_expression<T>
     {

libs/core/functional/include/hpx/functional/traits/is_placeholder.hpp

@@ -19,11 +19,17 @@
 
 namespace hpx {
 #if defined(DOXYGEN)
-    /// If \p T is a standard, Boost, or HPX placeholder (_1, _2, _3, ...) then
-    /// this template is derived from ``std::integral_constant<int, 1>``,
-    /// ``std::integral_constant<int, 2>``, ``std::integral_constant<int, 3>``,
-    /// respectively. Otherwise it is derived from ,
-    /// ``std::integral_constant<int, 0>``.
+    /// \brief If \c T is a standard, Boost, or HPX placeholder (_1, _2, _3, ...)
+    ///        then this template is derived from \c std::integral_constant<int,1>,
+    ///        \c std::integral_constant<int,2>, \c std::integral_constant<int,3>,
+    ///        respectively. Otherwise, it is derived from
+    ///        \c std::integral_constant<int,0>.
+    /// \details The template may be specialized for any user-defined \c T type: the
+    ///          specialization must satisfy \a UnaryTypeTrait with base characteristic
+    ///          of \c std::integral_constant<int,N> with N>0 to indicate that
+    ///          \c T should be treated as N'th placeholder type.
+    ///          \c hpx::bind uses \c hpx::is_placeholder to detect placeholders for
+    ///          unbound arguments.
     template <typename T>
     struct is_placeholder;
 #else