Add documentation clarifying FAILURE vs ERROR in CallbackReturn

rclcpp_lifecycle/include/rclcpp_lifecycle/node_interfaces/lifecycle_node_interface.hpp

@@ -53,17 +53,19 @@ class LifecycleNodeInterface
   LifecycleNodeInterface() {}
 
 public:
-  enum class CallbackReturn : uint8_t
-  {
-    SUCCESS = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_SUCCESS,
-    FAILURE = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_FAILURE,
-    ERROR = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_ERROR
-  };
-
-  /// Callback function for configure transition
-  /*
-   * \return SUCCESS by default
-   */
+enum class CallbackReturn : uint8_t
+{
+  /// The callback completed successfully and the transition can proceed.
+  SUCCESS = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_SUCCESS,
+
+  /// The callback did not succeed, and the transition will not proceed.
+  /// The node remains in its current state.
+  FAILURE = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_FAILURE,
+
+  /// An error occurred during the callback execution.
+  /// The node transitions to an error handling state.
+  ERROR = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_ERROR,
+};
   RCLCPP_LIFECYCLE_PUBLIC
   virtual CallbackReturn
   on_configure(const State & previous_state);