Add components documentation

docs/sphinx/api/public_distributed_api.rst

@@ -177,3 +177,64 @@ Member functions
    +----------------------------------------------------------+
    | :cpp:func:`hpx::distributed::latch::wait`                |
    +----------------------------------------------------------+
+
+``hpx/components.hpp``
+======================
+
+The header :hpx-header:`libs/full/include/include,hpx/include/components.hpp`
+includes the components implementation. A component in `hpx` is a C++ class
+which can be created remotely and for which its member functions can be invoked
+remotely as well. More information about how components can be defined,
+created, and used can be found in :ref:`components`.
+
+Macros
+------
+
+.. table:: `hpx` macros of header ``hpx/components.hpp``
+
+   +----------------------------------------------+
+   | Macro                                        |
+   +==============================================+
+   | :c:macro:`HPX_REGISTER_ACTION`               |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMPONENT`            |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMMANDLINE_REGISTRY` |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMMANDLINE_OPTIONS`  |
+   +----------------------------------------------+
+   | :c:macro:`HPX_DEFINE_COMPONENT_ACTION`       |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_ACTION_DECLARATION`   |
+   +----------------------------------------------+
+
+Classes
+-------
+
+.. table:: `hpx` classes of header ``hpx/components.hpp``
+
+   +----------------------------------------------------------+
+   | Class                                                    |
+   +==========================================================+
+   | :cpp:class:`hpx::components::client_base`                |
+   +----------------------------------------------------------+
+   | :cpp:class:`hpx::components::component`                  |
+   +----------------------------------------------------------+
+   | :cpp:class:`hpx::components::component_base`             |
+   +----------------------------------------------------------+
+   | :cpp:class:`hpx::components::component_commandline_base` |
+   +----------------------------------------------------------+
+
+
+Functions
+---------
+
+.. table:: `hpx` functions of header ``hpx/components.hpp``
+
+   +----------------------------------------------------------+
+   | Function                                                 |
+   +==========================================================+
+   | :cpp:func:`hpx::new_`                                    |
+   +----------------------------------------------------------+
+   | :cpp:func:`hpx::components::new_`                        |
+   +----------------------------------------------------------+

libs/core/runtime_configuration/include/hpx/runtime_configuration/component_commandline_base.hpp

@@ -4,6 +4,10 @@
 //  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 component_commandline_base.hpp
+/// \page HPX_REGISTER_COMMANDLINE_REGISTRY, HPX_REGISTER_COMMANDLINE_OPTIONS, hpx::components::component_commandline_base
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>

libs/full/components/include/hpx/components/client_base.hpp

@@ -4,6 +4,10 @@
 //  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 client_base.hpp
+/// \page hpx::components::client_base
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -279,6 +283,13 @@ namespace hpx::components {
     }    // namespace detail
 
     ///////////////////////////////////////////////////////////////////////////
+    /// This class template serves as a base class for client components,
+    /// providing common functionality such as managing shared state, ID
+    /// retrieval, and asynchronous operations.
+    ///
+    /// @tparam Derived The derived client component type.
+    /// @tparam Stub The stub type used for communication.
+    /// @tparam Data The extra data type used for additional information.
     template <typename Derived, typename Stub, typename Data>
     class client_base : public detail::make_stub<Stub>::type
     {

libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp

@@ -5,6 +5,10 @@
 //  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 components_base_fwd.hpp
+/// \page hpx::components::component, hpx::components::component_base
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -19,13 +23,20 @@ namespace hpx::components {
     template <typename Component>
     class fixed_component;
 
+    /// The \a component class wraps around a given component type, adding
+    /// additional type aliases and constructors. It inherits from the
+    /// specified component type.
     template <typename Component>
     class component;
 
     template <typename Component, typename Derived = void>
     class managed_component;
 
     ///////////////////////////////////////////////////////////////////////
+    /// \a component_base serves as a base class for components. It provides
+    /// common functionality needed by components, such as address and ID
+    /// retrieval. The template parameter \a Component specifies the
+    /// derived component type.
     template <typename Component = void>
     class component_base;
 

libs/full/runtime_components/include/hpx/runtime_components/new.hpp

@@ -5,6 +5,8 @@
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 /// \file new.hpp
+/// \page hpx::new_
+/// \headerfile hpx/components.hpp
 
 #pragma once
 
@@ -66,7 +68,7 @@ namespace hpx {
     ///          component instance.
     ///
     template <typename Component, typename... Ts>
-    <unspecified> new_(id_type const& locality, Ts&&... vs);
+    new_(id_type const& locality, Ts&&... vs);
 
     /// \brief Create one new instance of the given Component type on the
     /// current locality.
@@ -109,8 +111,7 @@ namespace hpx {
     ///          and non-movable. All operations are guaranteed to be local
     ///          only.
     ///
-    template <typename Component, typename... Ts>
-    <unspecified> local_new(Ts&&... vs);
+    template <typename Component, typename... Ts> local_new(Ts&&... vs);
 
     /// \brief Create multiple new instances of the given Component type on the
     /// specified locality.
@@ -155,7 +156,7 @@ namespace hpx {
     ///          components.
     ///
     template <typename Component, typename... Ts>
-    <unspecified> new_(id_type const& locality, std::size_t count, Ts&&... vs);
+    new_(id_type const& locality, std::size_t count, Ts&&... vs);
 
     /// \brief Create one or more new instances of the given Component type
     /// based on the given distribution policy.
@@ -194,7 +195,7 @@ namespace hpx {
     ///          component instance.
     ///
     template <typename Component, typename DistPolicy, typename... Ts>
-    <unspecified> new_(DistPolicy const& policy, Ts&&... vs);
+    new_(DistPolicy const& policy, Ts&&... vs);
 
     /// \brief Create multiple new instances of the given Component type on the
     /// localities as defined by the given distribution policy.
@@ -239,7 +240,7 @@ namespace hpx {
     ///          components.
     ///
     template <typename Component, typename DistPolicy, typename... Ts>
-    <unspecified> new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
+    new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
 }    // namespace hpx
 
 #else