Add documentation clarifying FAILURE vs ERROR in CallbackReturn

rclcpp_lifecycle/include/rclcpp_lifecycle/node_interfaces/lifecycle_node_interface.hpp

@@ -53,6 +53,15 @@ class LifecycleNodeInterface
   LifecycleNodeInterface() {}
 
 public:
+/// Return values for lifecycle transition callbacks.
+  ///
+  /// SUCCESS: The callback completed successfully and the transition can proceed.
+  ///
+  /// FAILURE: The callback did not succeed, and the transition will not proceed.
+  /// The node remains in its current state.
+  ///
+  /// ERROR: An error occurred during the callback execution.
+  /// The node may transition to an error handling state.
   enum class CallbackReturn : uint8_t
   {
     SUCCESS = lifecycle_msgs::msg::Transition::TRANSITION_CALLBACK_SUCCESS,