Improved rcl docblock (#659)

* Improved rcl docblock

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

* Added feedback

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

rcl/include/rcl/context.h

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

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

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

rcl/include/rcl/init.h

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

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

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.

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

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

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

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

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

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

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

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

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

rcl/include/rcl/wait.h

@@ -109,13 +109,15 @@ 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
  * \return `RCL_RET_ALREADY_INIT` if the wait set is not zero 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_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