Add doxygen coverage to nav2_behavior_tree

nav2_behavior_tree/include/nav2_behavior_tree/behavior_tree_engine.hpp

@@ -29,37 +29,82 @@
 namespace nav2_behavior_tree
 {
 
+/**
+ * @enum nav2_behavior_tree::BtStatus
+ * @brief An enum class representing BT execution status
+ */
 enum class BtStatus { SUCCEEDED, FAILED, CANCELED };
 
+/**
+ * @class nav2_behavior_tree::BehaviorTreeEngine
+ * @brief A class to create and handle behavior trees
+ */
 class BehaviorTreeEngine
 {
 public:
+  /**
+   * @brief A constructor for nav2_behavior_tree::BehaviorTreeEngine
+   * @param plugin_libraries vector of BT plugin library names to load
+   */
   explicit BehaviorTreeEngine(const std::vector<std::string> & plugin_libraries);
   virtual ~BehaviorTreeEngine() {}
 
+  /**
+   * @brief Function to execute a BT at a specific rate
+   * @param tree BT to execute
+   * @param onLoop Function to execute on each iteration of BT execution
+   * @param cancelRequested Function to check if cancel was requested during BT execution
+   * @param loopTimeout Time period for each iteration of BT execution
+   * @return nav2_behavior_tree::BtStatus Status of BT execution
+   */
   BtStatus run(
     BT::Tree * tree,
     std::function<void()> onLoop,
     std::function<bool()> cancelRequested,
     std::chrono::milliseconds loopTimeout = std::chrono::milliseconds(10));
 
+  /**
+   * @brief Function to create a BT from a XML string
+   * @param xml_string XML string representing BT
+   * @param blackboard Blackboard for BT
+   * @return BT::Tree Created behavior tree
+   */
   BT::Tree createTreeFromText(
     const std::string & xml_string,
     BT::Blackboard::Ptr blackboard);
 
+  /**
+   * @brief Function to create a BT from an XML file
+   * @param file_path Path to BT XML file
+   * @param blackboard Blackboard for BT
+   * @return BT::Tree Created behavior tree
+   */
   BT::Tree createTreeFromFile(
     const std::string & file_path,
     BT::Blackboard::Ptr blackboard);
 
+  /**
+   * @brief Add groot monitor to publish BT status changes
+   * @param tree BT to monitor
+   * @param publisher_port ZMQ publisher port for the Groot monitor
+   * @param server_port ZMQ server port for the Groot monitor
+   * @param max_msg_per_second Maximum number of messages that can be sent per second
+   */
   void addGrootMonitoring(
     BT::Tree * tree,
     uint16_t publisher_port,
     uint16_t server_port,
     uint16_t max_msg_per_second = 25);
 
+  /**
+   * @brief Reset groot monitor
+   */
   void resetGrootMonitor();
 
-  // In order to re-run a Behavior Tree, we must be able to reset all nodes to the initial state
+  /**
+   * @brief Function to explicitly reset all BT nodes to initial state
+   * @param root_node Pointer to BT root node
+   */
   void haltAllActions(BT::TreeNode * root_node);
 
 protected:

nav2_behavior_tree/include/nav2_behavior_tree/bt_action_node.hpp

@@ -26,10 +26,20 @@
 namespace nav2_behavior_tree
 {
 
+/**
+ * @brief Abstract class representing an action based BT node
+ * @tparam ActionT Type of action
+ */
 template<class ActionT>
 class BtActionNode : public BT::ActionNodeBase
 {
 public:
+  /**
+   * @brief A nav2_behavior_tree::BtActionNode constructor
+   * @param xml_tag_name Name for the XML tag for this node
+   * @param action_name Action name this node creates a client for
+   * @param conf BT node configuration
+   */
   BtActionNode(
     const std::string & xml_tag_name,
     const std::string & action_name,
@@ -63,7 +73,10 @@ class BtActionNode : public BT::ActionNodeBase
   {
   }
 
-  // Create instance of an action server
+  /**
+   * @brief Create instance of an action client
+   * @param action_name Action name to create client for
+   */
   void createActionClient(const std::string & action_name)
   {
     // Now that we have the ROS node to use, create the action client for this BT action
@@ -74,8 +87,12 @@ class BtActionNode : public BT::ActionNodeBase
     action_client_->wait_for_action_server();
   }
 
-  // Any subclass of BtActionNode that accepts parameters must provide a providedPorts method
-  // and call providedBasicPorts in it.
+  /**
+   * @brief Any subclass of BtActionNode that accepts parameters must provide a
+   * providedPorts method and call providedBasicPorts in it.
+   * @param addition Additional ports to add to BT port list
+   * @return BT::PortsList Containing basic ports along with node-specific ports
+   */
   static BT::PortsList providedBasicPorts(BT::PortsList addition)
   {
     BT::PortsList basic = {
@@ -87,6 +104,10 @@ class BtActionNode : public BT::ActionNodeBase
     return basic;
   }
 
+  /**
+   * @brief Creates list of BT ports
+   * @return BT::PortsList Containing basic ports along with node-specific ports
+   */
   static BT::PortsList providedPorts()
   {
     return providedBasicPorts({});
@@ -95,39 +116,54 @@ class BtActionNode : public BT::ActionNodeBase
   // Derived classes can override any of the following methods to hook into the
   // processing for the action: on_tick, on_wait_for_result, and on_success
 
-  // Could do dynamic checks, such as getting updates to values on the blackboard
+  /**
+   * @brief Function to perform some user-defined operation on tick
+   * Could do dynamic checks, such as getting updates to values on the blackboard
+   */
   virtual void on_tick()
   {
   }
 
-  // There can be many loop iterations per tick. Any opportunity to do something after
-  // a timeout waiting for a result that hasn't been received yet
+  /**
+   * @brief Function to perform some user-defined operation after a timeout
+   * waiting for a result that hasn't been received yet
+   */
   virtual void on_wait_for_result()
   {
   }
 
-  // Called upon successful completion of the action. A derived class can override this
-  // method to put a value on the blackboard, for example.
+  /**
+   * @brief Function to perform some user-defined operation upon successful
+   * completion of the action. Could put a value on the blackboard.
+   * @return BT::NodeStatus Returns SUCCESS by default, user may override return another value
+   */
   virtual BT::NodeStatus on_success()
   {
     return BT::NodeStatus::SUCCESS;
   }
 
-  // Called when a the action is aborted. By default, the node will return FAILURE.
-  // The user may override it to return another value, instead.
+  /**
+   * @brief Function to perform some user-defined operation whe the action is aborted.
+   * @return BT::NodeStatus Returns FAILURE by default, user may override return another value
+   */
   virtual BT::NodeStatus on_aborted()
   {
     return BT::NodeStatus::FAILURE;
   }
 
-  // Called when a the action is cancelled. By default, the node will return SUCCESS.
-  // The user may override it to return another value, instead.
+  /**
+   * @brief Function to perform some user-defined operation when the action is cancelled.
+   * @return BT::NodeStatus Returns SUCCESS by default, user may override return another value
+   */
   virtual BT::NodeStatus on_cancelled()
   {
     return BT::NodeStatus::SUCCESS;
   }
 
-  // The main override required by a BT action
+  /**
+   * @brief The main override required by a BT action
+   * @return BT::NodeStatus Status of tick execution
+   */
   BT::NodeStatus tick() override
   {
     // first step to be done only at the beginning of the Action
@@ -178,8 +214,10 @@ class BtActionNode : public BT::ActionNodeBase
     }
   }
 
-  // The other (optional) override required by a BT action. In this case, we
-  // make sure to cancel the ROS2 action if it is still running.
+  /**
+   * @brief The other (optional) override required by a BT action. In this case, we
+   * make sure to cancel the ROS2 action if it is still running.
+   */
   void halt() override
   {
     if (should_cancel_goal()) {
@@ -197,6 +235,10 @@ class BtActionNode : public BT::ActionNodeBase
   }
 
 protected:
+  /**
+   * @brief Function to check if current goal should be cancelled
+   * @return bool True if current goal should be cancelled, false otherwise
+   */
   bool should_cancel_goal()
   {
     // Shut the node down if it is currently running
@@ -212,7 +254,9 @@ class BtActionNode : public BT::ActionNodeBase
            status == action_msgs::msg::GoalStatus::STATUS_EXECUTING;
   }
 
-
+  /**
+   * @brief Function to send new goal to action server
+   */
   void on_new_goal_received()
   {
     goal_result_available_ = false;
@@ -242,6 +286,9 @@ class BtActionNode : public BT::ActionNodeBase
     }
   }
 
+  /**
+   * @brief Function to increment recovery count on blackboard if this node wraps a recovery
+   */
   void increment_recovery_count()
   {
     int recovery_count = 0;

nav2_behavior_tree/include/nav2_behavior_tree/bt_action_server.hpp

@@ -59,48 +59,47 @@ class BtActionServer
 
   /**
    * @brief Configures member variables
-   *
    * Initializes action server for, builds behavior tree from xml file,
    * and calls user-defined onConfigure.
-   * @return true on SUCCESS and false on FAILURE
+   * @return bool true on SUCCESS and false on FAILURE
    */
   bool on_configure();
 
   /**
    * @brief Activates action server
-   * @return true on SUCCESS and false on FAILURE
+   * @return bool true on SUCCESS and false on FAILURE
    */
   bool on_activate();
 
   /**
    * @brief Deactivates action server
-   * @return true on SUCCESS and false on FAILURE
+   * @return bool true on SUCCESS and false on FAILURE
    */
   bool on_deactivate();
 
   /**
    * @brief Resets member variables
-   * @return true on SUCCESS and false on FAILURE
+   * @return bool true on SUCCESS and false on FAILURE
    */
   bool on_cleanup();
 
   /**
    * @brief Called when in shutdown state
-   * @return true on SUCCESS and false on FAILURE
+   * @return bool true on SUCCESS and false on FAILURE
    */
   bool on_shutdown();
 
   /**
    * @brief Replace current BT with another one
    * @param bt_xml_filename The file containing the new BT, uses default filename if empty
-   * @return true if the resulting BT correspond to the one in bt_xml_filename. false
+   * @return bool true if the resulting BT correspond to the one in bt_xml_filename. false
    * if something went wrong, and previous BT is maintained
    */
   bool loadBehaviorTree(const std::string & bt_xml_filename = "");
 
   /**
    * @brief Getter function for BT Blackboard
-   * @return shared pointer to current BT blackboard
+   * @return BT::Blackboard::Ptr Shared pointer to current BT blackboard
    */
   BT::Blackboard::Ptr getBlackboard() const
   {
@@ -109,7 +108,7 @@ class BtActionServer
 
   /**
    * @brief Getter function for current BT XML filename
-   * @return string
+   * @return string Containing current BT XML filename
    */
   std::string getCurrentBTFilename() const
   {
@@ -118,6 +117,7 @@ class BtActionServer
 
   /**
    * @brief Wrapper function to accept pending goal if a preempt has been requested
+   * @return Shared pointer to pending action goal
    */
   const std::shared_ptr<const typename ActionT::Goal> acceptPendingGoal()
   {
@@ -126,6 +126,7 @@ class BtActionServer
 
   /**
    * @brief Wrapper function to get current goal
+   * @return Shared pointer to current action goal
    */
   const std::shared_ptr<const typename ActionT::Goal> getCurrentGoal() const
   {
@@ -142,6 +143,7 @@ class BtActionServer
 
   /**
    * @brief Getter function for the current BT tree
+   * @return BT::Tree Current behavior tree
    */
   BT::Tree getTree() const
   {

nav2_behavior_tree/include/nav2_behavior_tree/bt_conversions.hpp

@@ -30,6 +30,11 @@ namespace BT
 // in our BT XML files. They parse the strings in the XML into their corresponding
 // data type.
 
+/**
+ * @brief Parse XML string to geometry_msgs::msg::Point
+ * @param key XML string
+ * @return geometry_msgs::msg::Point
+ */
 template<>
 inline geometry_msgs::msg::Point convertFromString(const StringView key)
 {
@@ -46,6 +51,11 @@ inline geometry_msgs::msg::Point convertFromString(const StringView key)
   }
 }
 
+/**
+ * @brief Parse XML string to geometry_msgs::msg::Quaternion
+ * @param key XML string
+ * @return geometry_msgs::msg::Quaternion
+ */
 template<>
 inline geometry_msgs::msg::Quaternion convertFromString(const StringView key)
 {
@@ -63,6 +73,11 @@ inline geometry_msgs::msg::Quaternion convertFromString(const StringView key)
   }
 }
 
+/**
+ * @brief Parse XML string to geometry_msgs::msg::PoseStamped
+ * @param key XML string
+ * @return geometry_msgs::msg::PoseStamped
+ */
 template<>
 inline geometry_msgs::msg::PoseStamped convertFromString(const StringView key)
 {
@@ -85,6 +100,11 @@ inline geometry_msgs::msg::PoseStamped convertFromString(const StringView key)
   }
 }
 
+/**
+ * @brief Parse XML string to std::chrono::milliseconds
+ * @param key XML string
+ * @return std::chrono::milliseconds
+ */
 template<>
 inline std::chrono::milliseconds convertFromString<std::chrono::milliseconds>(const StringView key)
 {