Add components documentation

docs/sphinx/api/public_distributed_api.rst

@@ -177,3 +177,66 @@ 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_DEFINE_COMPONENT_ACTION`       |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_ACTION_DECLARATION`   |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_ACTION`               |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMMANDLINE_MODULE`   |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMPONENT`            |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_COMPONENT_MODULE`     |
+   +----------------------------------------------+
+   | :c:macro:`HPX_REGISTER_STARTUP_MODULE`       |
+   +----------------------------------------------+
+
+Classes
+-------
+
+.. table:: `hpx` classes of header ``hpx/components.hpp``
+
+   +----------------------------------------------------------+
+   | Class                                                    |
+   +==========================================================+
+   | :cpp:class:`hpx::components::client`                     |
+   +----------------------------------------------------------+
+   | :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_`                                    |
+   +----------------------------------------------------------+

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::components::component_commandline_base
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>

libs/core/runtime_configuration/include/hpx/runtime_configuration/component_factory_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.hpp
+/// \page HPX_REGISTER_COMPONENT_MODULE
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>

libs/full/actions_base/include/hpx/actions_base/basic_action.hpp

@@ -7,6 +7,8 @@
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 /// \file hpx/actions_base/basic_action.hpp
+/// \page HPX_REGISTER_ACTION_DECLARATION, HPX_REGISTER_ACTION
+/// \headerfile hpx/components.hpp
 
 #pragma once
 

libs/full/actions_base/include/hpx/actions_base/component_action.hpp

@@ -5,6 +5,8 @@
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 /// \file component_action.hpp
+/// \page HPX_DEFINE_COMPONENT_ACTION
+/// \headerfile hpx/components.hpp
 
 #pragma once
 

libs/full/components/include/hpx/components/client.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.hpp
+/// \page hpx::components::client
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -14,6 +18,11 @@
 
 namespace hpx::components {
 
+    /// @brief The client class is a wrapper that manages a distributed component.
+    /// It extends \c client_base with specific \c Component and \c Data types.
+    ///
+    /// @tparam Component The type of the component.
+    /// @tparam Data The type of the data associated with the client (default is void).
     template <typename Component, typename Data = void>
     class client : public client_base<client<Component, Data>, Component, Data>
     {

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/component_commandline.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.hpp
+/// \page HPX_REGISTER_COMMANDLINE_MODULE
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -53,6 +57,15 @@ namespace hpx::components {
     /***/
 
 ///////////////////////////////////////////////////////////////////////////////
+/**
+ * @brief Macro to register a command-line module with the HPX runtime.
+ *
+ * This macro facilitates the registration of a command-line module with the HPX
+ * runtime system. A command-line module typically provides additional command-line
+ * options that can be used to configure the HPX application.
+ *
+ * @param add_options_function The function that adds custom command-line options.
+ */
 #define HPX_REGISTER_COMMANDLINE_MODULE(add_options_function)                  \
     HPX_REGISTER_COMMANDLINE_OPTIONS()                                         \
     HPX_REGISTER_COMMANDLINE_REGISTRY(                                         \

libs/full/components_base/include/hpx/components_base/component_startup_shutdown.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.hpp
+/// \page HPX_REGISTER_STARTUP_MODULE
+/// \headerfile hpx/components.hpp
+
 #pragma once
 
 #include <hpx/config.hpp>
@@ -119,6 +123,15 @@ namespace hpx::components {
         startup_shutdown)                                                      \
     /**/
 
+/**
+ * @brief Macro to register a startup module with the HPX runtime.
+ *
+ * This macro facilitates the registration of a startup module with the HPX runtime system.
+ * A startup module typically contains initialization code that should be executed when the
+ * HPX runtime starts.
+ *
+ * @param startup The name of the startup function to be registered.
+ */
 #define HPX_REGISTER_STARTUP_MODULE(startup)                                   \
     HPX_REGISTER_STARTUP_SHUTDOWN_FUNCTIONS()                                  \
     HPX_REGISTER_STARTUP_SHUTDOWN_MODULE_(startup, 0)                          \

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/component_factory.hpp

@@ -6,6 +6,8 @@
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 /// \file hpx/runtime_components/component_factory.hpp
+/// \page HPX_REGISTER_COMPONENT
+/// \headerfile hpx/components.hpp
 
 #pragma once
 

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);
+    auto new_(id_type const& locality, Ts&&... vs);
 
     /// \brief Create one new instance of the given Component type on the
     /// current locality.
@@ -110,7 +112,7 @@ namespace hpx {
     ///          only.
     ///
     template <typename Component, typename... Ts>
-    <unspecified> local_new(Ts&&... vs);
+    auto local_new(Ts&&... vs);
 
     /// \brief Create multiple new instances of the given Component type on the
     /// specified locality.
@@ -155,7 +157,7 @@ namespace hpx {
     ///          components.
     ///
     template <typename Component, typename... Ts>
-    <unspecified> new_(id_type const& locality, std::size_t count, Ts&&... vs);
+    auto 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 +196,7 @@ namespace hpx {
     ///          component instance.
     ///
     template <typename Component, typename DistPolicy, typename... Ts>
-    <unspecified> new_(DistPolicy const& policy, Ts&&... vs);
+    auto 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 +241,7 @@ namespace hpx {
     ///          components.
     ///
     template <typename Component, typename DistPolicy, typename... Ts>
-    <unspecified> new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
+    auto new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
 }    // namespace hpx
 
 #else