From ae0296f43ae4951f1226818ae61ea955f882530c Mon Sep 17 00:00:00 2001 From: Felix Penzlin Date: Mon, 18 Mar 2024 13:26:54 +0100 Subject: [PATCH] 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 Co-authored-by: Chris Lalancette --- rcl/include/rcl/graph.h | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/rcl/include/rcl/graph.h b/rcl/include/rcl/graph.h index 2049359c8..59663d321 100644 --- a/rcl/include/rcl/graph.h +++ b/rcl/include/rcl/graph.h @@ -401,16 +401,17 @@ 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: @@ -418,7 +419,9 @@ rcl_names_and_types_fini(rcl_names_and_types_t * names_and_types); * ```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 + * } * ``` * *
@@ -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.