document out parameters for rcl_get_node_names and rcl_get_node_names…

…_with_enclaves (#1137)

* document out params for rcl_get_node_names

Signed-off-by: Felix Penzlin <[email protected]>
Co-authored-by: Chris Lalancette <[email protected]>

rcl/include/rcl/graph.h

@@ -401,24 +401,27 @@ RCL_WARN_UNUSED
 rcl_ret_t
 rcl_names_and_types_fini(rcl_names_and_types_t * names_and_types);
 
-/// Return a list of available nodes in the ROS graph.
+/// Return a list of node names and their associated namespaces in the ROS graph.
 /**
  * The `node` parameter must point to a valid node.
  *
- * The `node_names` parameter must be allocated and zero initialized.
- * `node_names` is the output for this function, and contains allocated memory.
+ * The `node_names` and `node_namespaces` parameters must be allocated and zero initialized.
+ * `node_names` and `node_namespaces` are the output for this function,
+ * and contain allocated memory.
  * Use rcutils_get_zero_initialized_string_array() for initializing an empty
  * rcutils_string_array_t struct.
- * This `node_names` struct should therefore be passed to rcutils_string_array_fini()
- * when it is no longer needed.
+ * These `node_names` and `node_namespaces` structs should therefore be passed
+ * to rcutils_string_array_fini() when they are no longer needed.
  * Failing to do so will result in leaked memory.
  *
  * Example:
  *
  * ```c
  * rcutils_string_array_t node_names =
  *   rcutils_get_zero_initialized_string_array();
- * rcl_ret_t ret = rcl_get_node_names(node, &node_names);
+ * rcutils_string_array_t node_namespaces =
+ *   rcutils_get_zero_initialized_string_array();
+ * rcl_ret_t ret = rcl_get_node_names(node, &node_names, &node_namespaces);
  * if (ret != RCL_RET_OK) {
  *   // ... error handling
  * }
@@ -427,6 +430,10 @@ rcl_names_and_types_fini(rcl_names_and_types_t * names_and_types);
  * if (rcutils_ret != RCUTILS_RET_OK) {
  *   // ... error handling
  * }
+ * rcutils_ret_t rcutils_ret = rcutils_string_array_fini(&node_namespaces);
+ * if (rcutils_ret != RCUTILS_RET_OK) {
+ *   // ... error handling
+ * }
  * ```
  *
  * <hr>
@@ -458,7 +465,7 @@ rcl_get_node_names(
   rcutils_string_array_t * node_names,
   rcutils_string_array_t * node_namespaces);
 
-/// Return a list of available nodes in the ROS graph, including their enclave names.
+/// Return a list of node names and their associated namespaces and enclaves in the ROS graph.
 /**
  * An rcl_get_node_names() equivalent, but including in its output the enclave
  * name the node is using.