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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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