niklas/rcl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improved rcl docblock (#659)

Browse source 
* Improved rcl docblock

Signed-off-by: ahcorde <ahcorde@gmail.com>

* Added feedback

Signed-off-by: ahcorde <ahcorde@gmail.com>
This commit is contained in:
Alejandro Hernández Cordero 2020-05-27 08:38:44 +02:00 • committed by GitHub
parent 75e475819b
commit c212a0dba4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 34 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

1
rcl/include/rcl/context.h
View file

@ -168,6 +168,7 @@ rcl_get_zero_initialized_context(void);
* Lock-Free | Yes [1]
* <i>[1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t`</i>
*
* \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.

5
rcl/include/rcl/event.h
View file

@ -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

2
rcl/include/rcl/graph.h
View file

@ -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

1
rcl/include/rcl/init.h
View file

@ -100,6 +100,7 @@ rcl_init(
* Lock-Free | Yes [1]
* <i>[1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t`</i>
*
* \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

1
rcl/include/rcl/logging.h
View file

@ -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

7
rcl/include/rcl/logging_rosout.h
View file

@ -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.

1
rcl/include/rcl/node.h
View file

@ -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

1
rcl/include/rcl/node_options.h
View file

@ -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

15
rcl/include/rcl/publisher.h
View file

@ -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)
/**

3
rcl/include/rcl/security.h
View file

@ -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

1
rcl/include/rcl/service.h
View file

@ -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

3
rcl/include/rcl/subscription.h
View file

@ -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

2
rcl/include/rcl/time.h
View file

@ -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.</i>
*
* \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

3
rcl/include/rcl/timer.h
View file

@ -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

2
rcl/include/rcl/validate_enclave_name.h
View file

@ -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

5
rcl/include/rcl/wait.h
View file

@ -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