Clarify rmw_destroy_node() side effects.

Signed-off-by: Michel Hidalgo <[email protected]>

Author: hidmic

rmw/include/rmw/rmw.h

@@ -173,6 +173,11 @@ rmw_create_node(
 
 /// Finalize a given node handle, reclaim the resources, and deallocate the node handle.
 /**
+ * This function will return early if a logical error, such as `RMW_RET_INVALID_ARGUMENT`
+ * or `RMW_RET_INCORRECT_RMW_IMPLEMENTATION`, ensues, leaving the given node handle unchanged.
+ * Otherwise, it will proceed despite errors, freeing as much resources as it can, including
+ * the node handle. Usage of a deallocated node handle is undefined behavior.
+ *
  * \pre All publishers, subscribers, services, and clients created from this node must
  *   have been destroyed prior to this call. Some rmw implementations may verify this,
  *   returning `RMW_RET_ERROR` and setting a human readable error message if any entity