resolve some todo questions

rcl/include/rcl/guard_condition.h

@@ -145,7 +145,13 @@ rcl_guard_condition_trigger(const rcl_guard_condition_t * guard_condition);
  *   - guard_condition is NULL
  *   - guard_condition is invalid (never called init, called fini, or invalid node)
  *
- * The returned handle is only valid as long as the given guard_condition is valid.
+ * The returned handle is made invalid if the guard condition is finalized or
+ * if rcl_shutdown() is called.
+ * The returned handle is not guaranteed to be valid for the life time of the
+ * guard condition as it may be finalized and recreated itself.
+ * Therefore it is recommended to get the handle from the guard condition using
+ * this function each time it is needed and avoid use of the handle
+ * concurrently with functions that might change it.
  *
  * \param[in] guard_condition pointer to the rcl guard_condition
  * \return rmw guard_condition handle if successful, otherwise NULL

rcl/include/rcl/node.h

@@ -63,7 +63,7 @@ rcl_node_t
 rcl_get_zero_initialized_node();
 
 /// Initialize a ROS node.
-/* Calling this on a rcl_node_t makes it a valid node handle until rcl_fini
+/* Calling this on a rcl_node_t makes it a valid node handle until rcl_shutdown
  * is called or until rcl_node_fini is called on it.
  *
  * After calling the ROS node object can be used to create other middleware
@@ -194,9 +194,14 @@ rcl_node_get_domain_id(const rcl_node_t * node, size_t * domain_id);
  *   - node is NULL
  *   - node has not been initialized (the implementation is invalid)
  *
- * The returned handle is only valid as long as the given node is valid.
+ * The returned handle is made invalid if the node is finalized or if
+ * rcl_shutdown() is called.
+ * The returned handle is not guaranteed to be valid for the life time of the
+ * node as it may be finalized and recreated itself.
+ * Therefore it is recommended to get the handle from the node using
+ * this function each time it is needed and avoid use of the handle
+ * concurrently with functions that might change it.
  *
- * \TODO(wjwwood) should the return value of this be const?
  *
  * \param[in] node pointer to the rcl node
  * \return rmw node handle if successful, otherwise NULL
@@ -214,8 +219,8 @@ rcl_node_get_rmw_node_handle(const rcl_node_t * node);
  *   - node is NULL
  *   - node has not been initialized (the implementation is invalid)
  *
- * This function will succeed, however, even if rcl_fini has been called since
+ * This function will succeed, however, even if rcl_shutdown has been called
- * the node was created.
+ * since the node was created.
  *
  * \param[in] node pointer to the rcl node
  * \return rcl instance id captured at node creation or 0 if there was an error

rcl/include/rcl/publisher.h

@@ -250,16 +250,13 @@ rcl_publisher_get_options(const rcl_publisher_t * publisher);
  *   - publisher is NULL
  *   - publisher is invalid (never called init, called fini, or invalid node)
  *
- * The returned handle is only valid as long as the given publisher is valid.
+ * The returned handle is made invalid if the publisher is finalized or if
- *
+ * rcl_shutdown() is called.
- * \TODO(wjwwood) will the publisher ever need to remove and recreate the rmw
+ * The returned handle is not guaranteed to be valid for the life time of the
- *                handle under the hood? Perhaps not now, but if we add the
+ * publisher as it may be finalized and recreated itself.
- *                ability to reconfigure, alias, or remap topics, and don't
+ * Therefore it is recommended to get the handle from the publisher using
- *                implement that into rmw, then we should consider the
+ * this function each time it is needed and avoid use of the handle
- *                implications here. This argument applies to other parts of
+ * concurrently with functions that might change it.
- *                the interface, but I'll just mention it here.
- *
- * \TODO(wjwwood) should the return value of this be const?
  *
  * \param[in] publisher pointer to the rcl publisher
  * \return rmw publisher handle if successful, otherwise NULL

rcl/include/rcl/subscription.h

@@ -222,7 +222,6 @@ rcl_take(
  * copying the string is recommended if this is a concern.
  *
  * This function is not thread-safe, and copying the result is not thread-safe.
- * \TODO(wjwwood): should we provide a thread-safe copy_topic_name?
  *
  * \param[in] subscription the pointer to the subscription
  * \return name string if successful, otherwise NULL
@@ -242,7 +241,6 @@ rcl_subscription_get_topic_name(const rcl_subscription_t * subscription);
  * and therefore copying the struct is recommended if this is a concern.
  *
  * This function is not thread-safe, and copying the result is not thread-safe.
- * \TODO(wjwwood): should we provide a thread-safe copy_subscription_options?
  *
  * \param[in] subscription pointer to the subscription
  * \return options struct if successful, otherwise NULL
@@ -257,9 +255,13 @@ rcl_subscription_get_options(const rcl_subscription_t * subscription);
  *   - subscription is NULL
  *   - subscription is invalid (never called init, called fini, or invalid)
  *
- * The returned handle is only valid as long as the rcl subscription is valid.
+ * The returned handle is made invalid if the subscription is finalized or if
- *
+ * rcl_shutdown() is called.
- * \TODO(wjwwood) should the return value of this be const?
+ * The returned handle is not guaranteed to be valid for the life time of the
+ * subscription as it may be finalized and recreated itself.
+ * Therefore it is recommended to get the handle from the subscription using
+ * this function each time it is needed and avoid use of the handle
+ * concurrently with functions that might change it.
  *
  * This function is not thread-safe.
  *