add some documentation to classes

Author: facontidavide

include/behaviortree_cpp/actions/script_node.h

@@ -18,6 +18,18 @@
 
 namespace BT
 {
+/**
+ * @brief The ScriptNode executes a piece of script code to set or modify
+ * entries in the Blackboard.
+ *
+ * The script is passed via the input port "code" and can use the BT++ scripting
+ * language syntax. For instance:
+ *
+ *   <Script code=" msg:='hello world' " />
+ *   <Script code=" A:=42; B:=3.14 " />
+ *
+ * The node always returns SUCCESS after executing the script.
+ */
 class ScriptNode : public SyncActionNode
 {
 public:

include/behaviortree_cpp/condition_node.h

@@ -18,6 +18,16 @@
 
 namespace BT
 {
+/**
+ * @brief The ConditionNode is a leaf node used to check a condition.
+ *
+ * Unlike ActionNodes, a ConditionNode should NOT alter the system
+ * and should NOT return RUNNING. It should return SUCCESS or FAILURE
+ * synchronously to indicate whether a condition is met.
+ *
+ * Conditions are typically used to check the state of the world or
+ * the system before performing an action (e.g., "IsDoorOpen", "IsBatteryLow").
+ */
 class ConditionNode : public LeafNode
 {
 public:

include/behaviortree_cpp/control_node.h

@@ -19,6 +19,15 @@
 
 namespace BT
 {
+/**
+ * @brief The ControlNode is the base class for nodes that can have multiple children.
+ *
+ * ControlNodes determine the order and conditions under which their children are
+ * ticked.
+ *
+ * Each derived class implements specific rules about if, when, and how many
+ * times children are ticked.
+ */
 class ControlNode : public TreeNode
 {
 protected:

include/behaviortree_cpp/decorator_node.h

@@ -5,6 +5,16 @@
 
 namespace BT
 {
+/**
+ * @brief The DecoratorNode is the base class for nodes that have exactly one child.
+ *
+ * DecoratorNodes modify the behavior of their child in some way.
+ * They may:
+ * - Transform the result received from the child (e.g., Inverter)
+ * - Control when or how many times the child is ticked (e.g., Repeat, Retry)
+ * - Add timing constraints (e.g., Timeout, Delay)
+ * - Conditionally execute the child (e.g., Precondition)
+ */
 class DecoratorNode : public TreeNode
 {
 protected:

include/behaviortree_cpp/decorators/force_failure_node.h

@@ -17,7 +17,11 @@
 namespace BT
 {
 /**
- * @brief The ForceFailureNode returns always FAILURE or RUNNING.
+ * @brief The ForceFailureNode always returns FAILURE when the child completes,
+ * regardless of whether the child returned SUCCESS or FAILURE.
+ *
+ * - If the child returns RUNNING, this node returns RUNNING.
+ * - If the child returns SUCCESS or FAILURE, this node returns FAILURE.
  */
 class ForceFailureNode : public DecoratorNode
 {

include/behaviortree_cpp/decorators/force_success_node.h

@@ -17,7 +17,11 @@
 namespace BT
 {
 /**
- * @brief The ForceSuccessNode returns always SUCCESS or RUNNING.
+ * @brief The ForceSuccessNode always returns SUCCESS when the child completes,
+ * regardless of whether the child returned SUCCESS or FAILURE.
+ *
+ * - If the child returns RUNNING, this node returns RUNNING.
+ * - If the child returns SUCCESS or FAILURE, this node returns SUCCESS.
  */
 class ForceSuccessNode : public DecoratorNode
 {

include/behaviortree_cpp/decorators/keep_running_until_failure_node.h

@@ -18,7 +18,14 @@
 namespace BT
 {
 /**
- * @brief The KeepRunningUntilFailureNode returns always FAILURE or RUNNING.
+ * @brief The KeepRunningUntilFailureNode keeps ticking the child as long
+ * as it returns SUCCESS, and returns RUNNING.
+ *
+ * - If the child returns SUCCESS, reset the child and return RUNNING.
+ * - If the child returns RUNNING, return RUNNING.
+ * - If the child returns FAILURE, return FAILURE.
+ *
+ * This creates an infinite loop that stops only when the child fails.
  */
 class KeepRunningUntilFailureNode : public DecoratorNode
 {

include/behaviortree_cpp/decorators/script_precondition.h

@@ -19,6 +19,22 @@
 
 namespace BT
 {
+/**
+ * @brief The PreconditionNode evaluates a script condition before ticking its child.
+ *
+ * If the script in the "if" port returns true, the child is ticked.
+ * If the script returns false, the node returns the status specified in the "else" port
+ * (FAILURE by default).
+ *
+ * Once the child starts (returns RUNNING), subsequent ticks will continue
+ * executing the child without re-evaluating the precondition until completion.
+ *
+ * Example usage:
+ *
+ *   <Precondition if="A > B && color != BLUE" else="FAILURE">
+ *     <SomeAction/>
+ *   </Precondition>
+ */
 class PreconditionNode : public DecoratorNode
 {
 public: