From c212a0dba4c0fbb833429e38992a0f765b84910e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Hern=C3=A1ndez=20Cordero?= Date: Wed, 27 May 2020 08:38:44 +0200 Subject: [PATCH] Improved rcl docblock (#659) * Improved rcl docblock Signed-off-by: ahcorde * Added feedback Signed-off-by: ahcorde --- rcl/include/rcl/context.h | 1 + rcl/include/rcl/event.h | 5 ++++- rcl/include/rcl/graph.h | 2 ++ rcl/include/rcl/init.h | 1 + rcl/include/rcl/logging.h | 1 + rcl/include/rcl/logging_rosout.h | 7 +++---- rcl/include/rcl/node.h | 1 + rcl/include/rcl/node_options.h | 1 + rcl/include/rcl/publisher.h | 15 +++++++-------- rcl/include/rcl/security.h | 3 +++ rcl/include/rcl/service.h | 1 + rcl/include/rcl/subscription.h | 3 ++- rcl/include/rcl/time.h | 2 +- rcl/include/rcl/timer.h | 3 --- rcl/include/rcl/validate_enclave_name.h | 2 +- rcl/include/rcl/wait.h | 5 +++++ 16 files changed, 34 insertions(+), 19 deletions(-) diff --git a/rcl/include/rcl/context.h b/rcl/include/rcl/context.h index 633e3bd83..36dd33d58 100644 --- a/rcl/include/rcl/context.h +++ b/rcl/include/rcl/context.h @@ -168,6 +168,7 @@ rcl_get_zero_initialized_context(void); * Lock-Free | Yes [1] * [1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t` * + * \param[inout] context object to be finalized. * \return `RCL_RET_OK` if the shutdown was completed successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_ERROR` if an unspecified error occur. diff --git a/rcl/include/rcl/event.h b/rcl/include/rcl/event.h index 6daebe1ec..01def23d0 100644 --- a/rcl/include/rcl/event.h +++ b/rcl/include/rcl/event.h @@ -72,6 +72,7 @@ rcl_get_zero_initialized_event(void); * \param[in] event_type to listen for * \return `RCL_RET_OK` if the rcl_event_t is filled, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_BAD_ALLOC` if allocating memory fails, or * \return `RCL_RET_UNSUPPORTED` if event_type is not supported, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ @@ -92,6 +93,7 @@ rcl_publisher_event_init( * \param[in] event_type to listen for * \return `RCL_RET_OK` if the rcl_event_t is filled, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_BAD_ALLOC` if allocating memory fails, or * \return `RCL_RET_UNSUPPORTED` if event_type is not supported, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ @@ -109,9 +111,10 @@ rcl_subscription_event_init( * * \param[in] event_handle event object to take from * \param[in, out] event_info event info object to write taken data into - * \param[in, out] taken boolean flag indicating if an event was taken or not * \return `RCL_RET_OK` if successful, or + * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_BAD_ALLOC` if memory allocation failed, or + * \return `RCL_RET_EVENT_TAKE_FAILED` if the take event failed, or * \return `RCL_RET_ERROR` if an unexpected error occurs. */ RCL_PUBLIC diff --git a/rcl/include/rcl/graph.h b/rcl/include/rcl/graph.h index 01da9bec6..ea651f7c2 100644 --- a/rcl/include/rcl/graph.h +++ b/rcl/include/rcl/graph.h @@ -430,6 +430,7 @@ rcl_names_and_types_fini(rcl_names_and_types_t * names_and_types); * \param[out] node_namesspaces struct storing discovered node namespaces * \return `RCL_RET_OK` if the query was successful, or * \return `RCL_RET_BAD_ALLOC` if an error occurred while allocating memory, or + * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ RCL_PUBLIC @@ -462,6 +463,7 @@ rcl_get_node_names( * \param[out] enclaves struct storing discovered node enclaves * \return `RCL_RET_OK` if the query was successful, or * \return `RCL_RET_BAD_ALLOC` if an error occurred while allocating memory, or + * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ RCL_PUBLIC diff --git a/rcl/include/rcl/init.h b/rcl/include/rcl/init.h index 6ff623272..315bc4ba0 100644 --- a/rcl/include/rcl/init.h +++ b/rcl/include/rcl/init.h @@ -100,6 +100,7 @@ rcl_init( * Lock-Free | Yes [1] * [1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t` * + * \param[inout] context object to shutdown * \return `RCL_RET_OK` if the shutdown was completed successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_ALREADY_SHUTDOWN` if the context is not currently valid, or diff --git a/rcl/include/rcl/logging.h b/rcl/include/rcl/logging.h index 1304e65a4..02f7b16a2 100644 --- a/rcl/include/rcl/logging.h +++ b/rcl/include/rcl/logging.h @@ -47,6 +47,7 @@ typedef rcutils_logging_output_handler_t rcl_logging_output_handler_t; * \param allocator Used to allocate memory used by the logging system * \return `RCL_RET_OK` if successful, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or + * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_ERR` if a general error occurs */ RCL_PUBLIC diff --git a/rcl/include/rcl/logging_rosout.h b/rcl/include/rcl/logging_rosout.h index 279363fa2..8e6788c92 100644 --- a/rcl/include/rcl/logging_rosout.h +++ b/rcl/include/rcl/logging_rosout.h @@ -93,9 +93,8 @@ rcl_logging_rosout_fini(); * Lock-Free | Yes * * \param[in] node a valid rcl_node_t that the publisher will be created on - * \return `RCL_RET_OK` if the publisher was created successfully, or - * \return `RCL_RET_ALREADY_INIT` if the publisher has already exists, or - * \return `RCL_RET_NODE_INVALID` if any arguments are invalid, or + * \return `RCL_RET_OK` if the logging publisher was created successfully, or + * \return `RCL_RET_NODE_INVALID` if the argument is invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ @@ -120,7 +119,7 @@ rcl_logging_rosout_init_publisher_for_node( * Lock-Free | Yes * * \param[in] node a valid rcl_node_t that the publisher will be created on - * \return `RCL_RET_OK` if the publisher was created successfully, or + * \return `RCL_RET_OK` if the logging publisher was finalized successfully, or * \return `RCL_RET_NODE_INVALID` if any arguments are invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_ERROR` if an unspecified error occurs. diff --git a/rcl/include/rcl/node.h b/rcl/include/rcl/node.h index 2c3109450..0d5de91df 100644 --- a/rcl/include/rcl/node.h +++ b/rcl/include/rcl/node.h @@ -132,6 +132,7 @@ rcl_get_zero_initialized_node(void); * pass in. * \return `RCL_RET_OK` if the node was initialized successfully, or * \return `RCL_RET_ALREADY_INIT` if the node has already be initialized, or + * \return `RCL_RET_NOT_INIT` if the given context is invalid, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_NODE_INVALID_NAME` if the name is invalid, or diff --git a/rcl/include/rcl/node_options.h b/rcl/include/rcl/node_options.h index 15dfeed6e..ab10fa533 100644 --- a/rcl/include/rcl/node_options.h +++ b/rcl/include/rcl/node_options.h @@ -71,6 +71,7 @@ typedef struct rcl_node_options_t * - domain_id = RCL_NODE_OPTIONS_DEFAULT_DOMAIN_ID * - allocator = rcl_get_default_allocator() * - use_global_arguments = true + * - enable_rosout = true * - arguments = rcl_get_zero_initialized_arguments() */ RCL_PUBLIC diff --git a/rcl/include/rcl/publisher.h b/rcl/include/rcl/publisher.h index 5a623f3b8..aeca4bb12 100644 --- a/rcl/include/rcl/publisher.h +++ b/rcl/include/rcl/publisher.h @@ -152,8 +152,7 @@ rcl_publisher_init( const rcl_node_t * node, const rosidl_message_type_support_t * type_support, const char * topic_name, - const rcl_publisher_options_t * options -); + const rcl_publisher_options_t * options); /// Finalize a rcl_publisher_t. /** @@ -190,6 +189,7 @@ rcl_publisher_fini(rcl_publisher_t * publisher, rcl_node_t * node); * * - qos = rmw_qos_profile_default * - allocator = rcl_get_default_allocator() + * - rmw_publisher_options = rmw_get_default_publisher_options() */ RCL_PUBLIC RCL_WARN_UNUSED @@ -247,6 +247,7 @@ rcl_borrow_loaned_message( * \return `RCL_RET_OK` if successful, or * \return `RCL_RET_INVALID_ARGUMENT` if an argument is null, or * \return `RCL_RET_UNIMPLEMENTED` if the middleware does not support that feature, or + * \return `RCL_RET_PUBLISHER_INVALID` if the publisher is invalid, or * \return `RCL_RET_ERROR` if an unexpected error occurs and no message can be initialized. */ RCL_PUBLIC @@ -319,8 +320,7 @@ rcl_ret_t rcl_publish( const rcl_publisher_t * publisher, const void * ros_message, - rmw_publisher_allocation_t * allocation -); + rmw_publisher_allocation_t * allocation); /// Publish a serialized message on a topic using a publisher. /** @@ -349,6 +349,7 @@ rcl_publish( * \param[in] serialized_message pointer to the already serialized message in raw form * \param[in] allocation structure pointer, used for memory preallocation (may be NULL) * \return `RCL_RET_OK` if the message was published successfully, or + * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_PUBLISHER_INVALID` if the publisher is invalid, or * \return `RCL_RET_ERROR` if an unspecified error occurs. @@ -359,8 +360,7 @@ rcl_ret_t rcl_publish_serialized_message( const rcl_publisher_t * publisher, const rcl_serialized_message_t * serialized_message, - rmw_publisher_allocation_t * allocation -); + rmw_publisher_allocation_t * allocation); /// Publish a loaned message on a topic using a publisher. /** @@ -401,8 +401,7 @@ rcl_ret_t rcl_publish_loaned_message( const rcl_publisher_t * publisher, void * ros_message, - rmw_publisher_allocation_t * allocation -); + rmw_publisher_allocation_t * allocation); /// Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC) /** diff --git a/rcl/include/rcl/security.h b/rcl/include/rcl/security.h index 0de8777fa..b21bc3f01 100644 --- a/rcl/include/rcl/security.h +++ b/rcl/include/rcl/security.h @@ -55,6 +55,9 @@ extern "C" * \param[in] allocator used to do allocations. * \param[out] security_options security options that will be configured according to * the environment. + * \return `RCL_RET_OK` If the security options are returned properly, or + * \returns RCL_RET_INVALID_ARGUMENT if an argument is not valid, or + * \returns RCL_RET_ERROR if an unexpected error happened */ RCL_PUBLIC rcl_ret_t diff --git a/rcl/include/rcl/service.h b/rcl/include/rcl/service.h index 6c0ecb831..78c16a608 100644 --- a/rcl/include/rcl/service.h +++ b/rcl/include/rcl/service.h @@ -139,6 +139,7 @@ rcl_get_zero_initialized_service(void); * \param[in] options service options, including quality of service settings * \return `RCL_RET_OK` if service was initialized successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_ALREADY_INIT` if the service is already initialized, or * \return `RCL_RET_NODE_INVALID` if the node is invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_SERVICE_NAME_INVALID` if the given service name is invalid, or diff --git a/rcl/include/rcl/subscription.h b/rcl/include/rcl/subscription.h index 32ec51892..ccaea82cf 100644 --- a/rcl/include/rcl/subscription.h +++ b/rcl/include/rcl/subscription.h @@ -142,6 +142,7 @@ rcl_get_zero_initialized_subscription(void); * \param[in] options subscription options, including quality of service settings * \return `RCL_RET_OK` if subscription was initialized successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_ALREADY_INIT` if the subcription is already initialized, or * \return `RCL_RET_NODE_INVALID` if the node is invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_TOPIC_NAME_INVALID` if the given topic name is invalid, or @@ -193,9 +194,9 @@ rcl_subscription_fini(rcl_subscription_t * subscription, rcl_node_t * node); /** * The defaults are: * - * - ignore_local_publications = false * - qos = rmw_qos_profile_default * - allocator = rcl_get_default_allocator() + * - rmw_subscription_options = rmw_get_default_subscription_options(); */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/time.h b/rcl/include/rcl/time.h index e2854725b..a25086ece 100644 --- a/rcl/include/rcl/time.h +++ b/rcl/include/rcl/time.h @@ -259,6 +259,7 @@ rcl_clock_fini( * \param[in] allocator The allocator to use for allocations * \return `RCL_RET_OK` if the time source was successfully initialized, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or * \return `RCL_RET_ERROR` an unspecified error occur. */ RCL_PUBLIC @@ -671,7 +672,6 @@ rcl_clock_add_jump_callback( * `clock` object. * * \param[in] clock The clock to remove a jump callback from. - * \param[in] threshold Criteria indicating when to call callback. * \param[in] callback The callback to call. * \param[in] user_data A pointer to be passed to the callback. * \return `RCL_RET_OK` if the callback was added successfully, or diff --git a/rcl/include/rcl/timer.h b/rcl/include/rcl/timer.h index 7c679b552..ecc35f073 100644 --- a/rcl/include/rcl/timer.h +++ b/rcl/include/rcl/timer.h @@ -375,7 +375,6 @@ rcl_timer_get_time_since_last_call(const rcl_timer_t * timer, int64_t * time_sin * \param[out] period the int64_t in which the period is stored * \return `RCL_RET_OK` if the period was retrieved successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_TIMER_INVALID` if the timer is invalid, or * \return `RCL_RET_ERROR` an unspecified error occur. */ RCL_PUBLIC @@ -406,7 +405,6 @@ rcl_timer_get_period(const rcl_timer_t * timer, int64_t * period); * \param[out] old_period the int64_t in which the previous period is stored * \return `RCL_RET_OK` if the period was retrieved successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_TIMER_INVALID` if the timer is invalid, or * \return `RCL_RET_ERROR` an unspecified error occur. */ RCL_PUBLIC @@ -513,7 +511,6 @@ rcl_timer_cancel(rcl_timer_t * timer); * \param[out] is_canceled storage for the is canceled bool * \return `RCL_RET_OK` if the last call time was retrieved successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_TIMER_INVALID` if the timer is invalid, or * \return `RCL_RET_ERROR` an unspecified error occur. */ RCL_PUBLIC diff --git a/rcl/include/rcl/validate_enclave_name.h b/rcl/include/rcl/validate_enclave_name.h index 68e15e76e..7daee9bd7 100644 --- a/rcl/include/rcl/validate_enclave_name.h +++ b/rcl/include/rcl/validate_enclave_name.h @@ -67,7 +67,7 @@ rcl_validate_enclave_name( * This is an overload of \ref rcl_validate_enclave_name with an extra parameter * for the length of enclave. * - * \param[in] enclave The number of characters in enclave. + * \param[in] enclave_length The number of characters in enclave. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/wait.h b/rcl/include/rcl/wait.h index 10b615c12..5ca26113f 100644 --- a/rcl/include/rcl/wait.h +++ b/rcl/include/rcl/wait.h @@ -109,6 +109,7 @@ rcl_get_zero_initialized_wait_set(void); * \param[in] number_of_timers non-zero size of the timers set * \param[in] number_of_clients non-zero size of the clients set * \param[in] number_of_services non-zero size of the services set + * \param[in] number_of_events non-zero size of the events set * \param[in] context the context that the wait set should be associated with * \param[in] allocator the allocator to use when allocating space in the sets * \return `RCL_RET_OK` if the wait set is initialized successfully, or @@ -116,6 +117,7 @@ rcl_get_zero_initialized_wait_set(void); * \return `RCL_RET_NOT_INIT` if the given context is invalid, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or + * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is not destroyed properly, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ RCL_PUBLIC @@ -155,6 +157,7 @@ rcl_wait_set_init( * \param[inout] wait_set the wait set struct to be finalized. * \return `RCL_RET_OK` if the finalization was successful, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is not destroyed properly, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ RCL_PUBLIC @@ -179,6 +182,7 @@ rcl_wait_set_fini(rcl_wait_set_t * wait_set); * \param[out] allocator the rcl_allocator_t struct to which the result is copied * \return `RCL_RET_OK` if the allocator was successfully retrieved, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is invalid, or * \return `RCL_RET_ERROR` if an unspecified error occurs. */ RCL_PUBLIC @@ -280,6 +284,7 @@ rcl_wait_set_clear(rcl_wait_set_t * wait_set); * \param[in] timers_size a size for the new timers set * \param[in] clients_size a size for the new clients set * \param[in] services_size a size for the new services set + * \param[in] events_size a size for the new events set * \return `RCL_RET_OK` if resized successfully, or * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or