From bdd88a3b8dd285e9bdf132944d609e8de4684622 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alejandro=20Hern=C3=A1ndez=20Cordero?=
 <alejandro@openrobotics.org>
Date: Wed, 13 May 2020 08:17:56 +0200
Subject: [PATCH] Added dockblock to ComponentManager class (#1102)

* Added dockblock to ComponentManager class

Signed-off-by: ahcorde <ahcorde@gmail.com>

* added feedback

Signed-off-by: ahcorde <ahcorde@gmail.com>
---
 .../rclcpp_components/component_manager.hpp   | 50 +++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/rclcpp_components/include/rclcpp_components/component_manager.hpp b/rclcpp_components/include/rclcpp_components/component_manager.hpp
index 20d2d7b890..5e9074937b 100644
--- a/rclcpp_components/include/rclcpp_components/component_manager.hpp
+++ b/rclcpp_components/include/rclcpp_components/component_manager.hpp
@@ -40,6 +40,7 @@ class ClassLoader;
 namespace rclcpp_components
 {
 
+/// Thrown when an error happens in the component Manager class.
 class ComponentManagerException : public std::runtime_error
 {
 public:
@@ -47,6 +48,7 @@ class ComponentManagerException : public std::runtime_error
   : std::runtime_error(error_desc) {}
 };
 
+/// ComponentManager handles the services to load, unload, and get the list of loaded components.
 class ComponentManager : public rclcpp::Node
 {
 public:
@@ -60,6 +62,15 @@ class ComponentManager : public rclcpp::Node
    */
   using ComponentResource = std::pair<std::string, std::string>;
 
+  /// Default constructor
+  /**
+   * Initializes the component manager. It creates the services: load node, unload node
+   * and list nodes.
+   *
+   * \param executor the executor which will spin the node.
+   * \param node_name the name of the node that the data originates from.
+   * \param node_options additional options to control creation of the node.
+   */
   RCLCPP_COMPONENTS_PUBLIC
   ComponentManager(
     std::weak_ptr<rclcpp::Executor> executor,
@@ -70,17 +81,41 @@ class ComponentManager : public rclcpp::Node
   virtual ~ComponentManager();
 
   /// Return a list of valid loadable components in a given package.
+  /*
+   * \param package_name name of the package
+   * \param resource_index name of the executable
+   * \throws ComponentManagerException if the resource was not found or a invalid resource entry
+   * \return a list of component resources
+   */
   RCLCPP_COMPONENTS_PUBLIC
   virtual std::vector<ComponentResource>
   get_component_resources(
     const std::string & package_name,
     const std::string & resource_index = "rclcpp_components") const;
 
+  /// Instantiate a component from a dynamic library.
+  /*
+   * \param resource a component resource (class name + library path)
+   * \return a NodeFactory interface
+   */
   RCLCPP_COMPONENTS_PUBLIC
   virtual std::shared_ptr<rclcpp_components::NodeFactory>
   create_component_factory(const ComponentResource & resource);
 
 protected:
+  /// Service callback to load a new node in the component
+  /*
+   * This function allows to add parameters, remap rules, a specific node, name a namespace
+   * and/or additional arguments.
+   *
+   * \param request_header unused
+   * \param request information with the node to load
+   * \param response
+   * \throws std::overflow_error if node_id suffers an overflow. Very unlikely to happen at 1 kHz
+   *   (very optimistic rate). it would take 585 years.
+   * \throws ComponentManagerException In the case that the component constructor throws an
+   *   exception, rethrow into the following catch block.
+   */
   RCLCPP_COMPONENTS_PUBLIC
   virtual void
   OnLoadNode(
@@ -88,6 +123,13 @@ class ComponentManager : public rclcpp::Node
     const std::shared_ptr<LoadNode::Request> request,
     std::shared_ptr<LoadNode::Response> response);
 
+  /// Service callback to unload a node in the component
+  /*
+   * \param request_header unused
+   * \param request unique identifier to remove from the component
+   * \param response true on the success field if the node unload was succefully, otherwise false
+   *   and the error_message field contains the error.
+   */
   RCLCPP_COMPONENTS_PUBLIC
   virtual void
   OnUnloadNode(
@@ -95,6 +137,14 @@ class ComponentManager : public rclcpp::Node
     const std::shared_ptr<UnloadNode::Request> request,
     std::shared_ptr<UnloadNode::Response> response);
 
+  /// Service callback to get the list of nodes in the component
+  /*
+   * Return a two list: one with the unique identifiers and other with full name of the nodes.
+   *
+   * \param request_header unused
+   * \param request unused
+   * \param response list with the unique ids and full node names
+   */
   RCLCPP_COMPONENTS_PUBLIC
   virtual void
   OnListNodes(