diff --git a/rcl/include/rcl/allocator.h b/rcl/include/rcl/allocator.h index 1b3906f1e6..ab26fcf1f5 100644 --- a/rcl/include/rcl/allocator.h +++ b/rcl/include/rcl/allocator.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__ALLOCATOR_H_ #define RCL__ALLOCATOR_H_ @@ -22,15 +24,35 @@ extern "C" #include "rcutils/allocator.h" +/// Encapsulation of an allocator. +/** + * \sa rcutils_allocator_t + */ typedef rcutils_allocator_t rcl_allocator_t; +/// Return a properly initialized rcutils_allocator_t with default values. +/** + * \sa rcutils_get_default_allocator() + */ #define rcl_get_default_allocator rcutils_get_default_allocator +/// Emulate the behavior of [reallocf](https://linux.die.net/man/3/reallocf). +/** + * \sa rcutils_reallocf() + */ #define rcl_reallocf rcutils_reallocf +/// Check that the given allocator is initialized. +/** + * If the allocator is not initialized, run the fail_statement. + */ #define RCL_CHECK_ALLOCATOR(allocator, fail_statement) \ RCUTILS_CHECK_ALLOCATOR(allocator, fail_statement) +/// Check that the given allocator is initialized, or fail with a message. +/** + * If the allocator is not initialized, set the error to msg, and run the fail_statement. + */ #define RCL_CHECK_ALLOCATOR_WITH_MSG(allocator, msg, fail_statement) \ RCUTILS_CHECK_ALLOCATOR_WITH_MSG(allocator, msg, fail_statement) diff --git a/rcl/include/rcl/arguments.h b/rcl/include/rcl/arguments.h index bd2c25d965..54662b08c9 100644 --- a/rcl/include/rcl/arguments.h +++ b/rcl/include/rcl/arguments.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__ARGUMENTS_H_ #define RCL__ARGUMENTS_H_ @@ -36,20 +38,46 @@ typedef struct rcl_arguments_t struct rcl_arguments_impl_t * impl; } rcl_arguments_t; +/// The command-line flag that delineates the start of ROS arguments. #define RCL_ROS_ARGS_FLAG "--ros-args" + +/// The token that delineates the explicit end of ROS arguments. #define RCL_ROS_ARGS_EXPLICIT_END_TOKEN "--" + +/// The ROS flag that precedes the setting of a ROS parameter. #define RCL_PARAM_FLAG "--param" + +/// The short version of the ROS flag that precedes the setting of a ROS parameter. #define RCL_SHORT_PARAM_FLAG "-p" + +/// The ROS flag that precedes a path to a file containing ROS parameters. #define RCL_PARAM_FILE_FLAG "--params-file" + +/// The ROS flag that precedes a ROS remapping rule. #define RCL_REMAP_FLAG "--remap" + +/// The short version of the ROS flag that precedes a ROS remapping rule. #define RCL_SHORT_REMAP_FLAG "-r" + +/// The ROS flag that precedes the name of a ROS security enclave. #define RCL_ENCLAVE_FLAG "--enclave" + +/// The short version of the ROS flag that precedes the name of a ROS security enclave. #define RCL_SHORT_ENCLAVE_FLAG "-e" + +/// The ROS flag that precedes the ROS logging level to set. #define RCL_LOG_LEVEL_FLAG "--log-level" + +/// The ROS flag that precedes the name of a configuration file to configure logging. #define RCL_EXTERNAL_LOG_CONFIG_FLAG "--log-config-file" -// To be prefixed with --enable- or --disable- + +/// The suffix of the ROS flag to enable or disable stdout logging (must be preceded with --enable- or --disable-). #define RCL_LOG_STDOUT_FLAG_SUFFIX "stdout-logs" + +/// The suffix of the ROS flag to enable or disable rosout logging (must be preceded with --enable- or --disable-). #define RCL_LOG_ROSOUT_FLAG_SUFFIX "rosout-logs" + +/// The suffix of the ROS flag to enable or disable external library logging (must be preceded with --enable- or --disable-). #define RCL_LOG_EXT_LIB_FLAG_SUFFIX "external-lib-logs" /// Return a rcl_arguments_t struct with members initialized to `NULL`. @@ -109,11 +137,11 @@ rcl_get_zero_initialized_arguments(void); * \param[in] allocator A valid allocator. * \param[out] args_output A structure that will contain the result of parsing. * Must be zero initialized before use. - * \return `RCL_RET_OK` if the arguments were parsed successfully, or - * \return `RCL_RET_INVALID_ROS_ARGS` if an invalid ROS argument is found, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the arguments were parsed successfully, or + * \return #RCL_RET_INVALID_ROS_ARGS if an invalid ROS argument is found, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -164,10 +192,10 @@ rcl_arguments_get_count_unparsed( * \param[out] output_unparsed_indices An allocated array of indices into the original argv array. * This array must be deallocated by the caller using the given allocator. * If there are no unparsed args then the output will be set to NULL. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -216,10 +244,10 @@ rcl_arguments_get_count_unparsed_ros( * \param[out] output_unparsed_ros_indices An allocated array of indices into the original argv array. * This array must be deallocated by the caller using the given allocator. * If there are no unparsed ROS specific arguments then the output will be set to NULL. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -265,10 +293,10 @@ rcl_arguments_get_param_files_count( * \param[out] parameter_files An allocated array of paramter file names. * This array must be deallocated by the caller using the given allocator. * The output is NULL if there were no paramter files. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -295,10 +323,10 @@ rcl_arguments_get_param_files( * \param[out] parameter_overrides Parameter overrides as parsed from command line arguments. * This structure must be finalized by the caller. * The output is NULL if no parameter overrides were parsed. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -329,10 +357,10 @@ rcl_arguments_get_param_overrides( * \param[out] nonros_argv An allocated array of arguments that aren't ROS-specific * This array must be deallocated by the caller using the given allocator. * If there are no non-ROS args, then the output will be set to NULL. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -359,9 +387,9 @@ rcl_remove_ros_arguments( * \param[in] arguments An arguments structure that has been parsed. * \param[out] log_levels Log levels as parsed from command line arguments. * The output must be finished by the caller if the function successes. - * \return `RCL_RET_OK` if everything goes correctly, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed. + * \return #RCL_RET_OK if everything goes correctly, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -383,10 +411,10 @@ rcl_arguments_get_log_levels( * \param[in] args The structure to be copied. * Its allocator is used to copy memory into the new structure. * \param[out] args_out A zero-initialized arguments structure to be copied into. - * \return `RCL_RET_OK` if the structure was copied successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the structure was copied successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -406,9 +434,9 @@ rcl_arguments_copy( * Lock-Free | Yes * * \param[in] args The structure to be deallocated. - * \return `RCL_RET_OK` if the memory was successfully freed, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the memory was successfully freed, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/client.h b/rcl/include/rcl/client.h index 97dade4f25..e4285a0318 100644 --- a/rcl/include/rcl/client.h +++ b/rcl/include/rcl/client.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__CLIENT_H_ #define RCL__CLIENT_H_ @@ -142,13 +144,13 @@ rcl_get_zero_initialized_client(void); * \param[in] type_support type support object for the service's type * \param[in] service_name the name of the service to request * \param[in] options client options, including quality of service settings - * \return `RCL_RET_OK` if the client was initialized successfully, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ALREADY_INIT` if the client is already initialized, 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_SERVICE_NAME_INVALID` if the given service name is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the client was initialized successfully, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ALREADY_INIT if the client is already initialized, 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_SERVICE_NAME_INVALID if the given service name is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -176,10 +178,10 @@ rcl_client_init( * * \param[inout] client handle to the client to be finalized * \param[in] node a valid (not finalized) handle to the node used to create the client - * \return `RCL_RET_OK` if client was finalized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if client was finalized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -237,10 +239,10 @@ rcl_client_get_default_options(void); * \param[in] client handle to the client which will make the response * \param[in] ros_request type-erased pointer to the ROS request message * \param[out] sequence_number the sequence number - * \return `RCL_RET_OK` if the request was sent successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_CLIENT_INVALID` if the client is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the request was sent successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_CLIENT_INVALID if the client is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -276,12 +278,12 @@ rcl_send_request(const rcl_client_t * client, const void * ros_request, int64_t * \param[in] client handle to the client which will take the response * \param[inout] request_header pointer to the request header * \param[inout] ros_response type-erased pointer to the ROS response message - * \return `RCL_RET_OK` if the response was taken successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_CLIENT_INVALID` if the client is invalid, or - * \return `RCL_RET_CLIENT_TAKE_FAILED` if take failed but no error occurred + * \return #RCL_RET_OK if the response was taken successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_CLIENT_INVALID if the client is invalid, or + * \return #RCL_RET_CLIENT_TAKE_FAILED if take failed but no error occurred * in the middleware, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/context.h b/rcl/include/rcl/context.h index 9275364dba..b5604ddcc4 100644 --- a/rcl/include/rcl/context.h +++ b/rcl/include/rcl/context.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__CONTEXT_H_ #define RCL__CONTEXT_H_ @@ -29,13 +31,16 @@ extern "C" #include "rcl/types.h" #include "rcl/visibility_control.h" +/// @cond Doxygen_Suppress #ifdef _MSC_VER #define RCL_ALIGNAS(N) __declspec(align(N)) #else #include #define RCL_ALIGNAS(N) alignas(N) #endif +/// @endcond +/// A unique ID per context instance. typedef uint64_t rcl_context_instance_id_t; struct rcl_context_impl_t; @@ -73,42 +78,42 @@ struct rcl_context_impl_t; * +---------------------------------------------------------------------------------+ * ``` * - * A declared but not defined `rcl_context_t` instance is considered to be + * A declared but not defined rcl_context_t instance is considered to be * "uninitialized", and passing an uninitialized context to any functions will * result in undefined behavior. - * Some functions, like `rcl_init()` require the context instance to be + * Some functions, like rcl_init() require the context instance to be * zero initialized (all members set to "zero" state) before use. * - * Zero initialization of an `rcl_context_t` should be done with - * `rcl_get_zero_initialized_context()`, which ensures the context is in a safe - * state for initialization with `rcl_init()`. + * Zero initialization of an rcl_context_t should be done with + * rcl_get_zero_initialized_context(), which ensures the context is in a safe + * state for initialization with rcl_init(). * - * Initialization of an `rcl_context_t` should be done with `rcl_init()`, after + * Initialization of an rcl_context_t should be done with rcl_init(), after * which the context is considered both initialized and valid. * After initialization it can be used in the creation of other entities like * nodes and guard conditions. * - * At any time the context can be invalidated by calling `rcl_shutdown()` on - * the `rcl_context_t`, after which the context is still initialized but now + * At any time the context can be invalidated by calling rcl_shutdown() on + * the rcl_context_t, after which the context is still initialized but now * invalid. * * Invalidation indicates to other entities that the context was shutdown, but * is still accessible for use during cleanup of themselves. * * After being invalidated, and after all of the entities which used it have - * been finalized, the context should be finalized with `rcl_context_fini()`. + * been finalized, the context should be finalized with rcl_context_fini(). * * Finalizing the context while entities which have copies of it have not yet * been finalized is undefined behavior. - * Therefore, the context's lifetime (between calls to `rcl_init()` and - * `rcl_context_fini()`) should exceed the lifetime of all entities which use + * Therefore, the context's lifetime (between calls to rcl_init() and + * rcl_context_fini()) should exceed the lifetime of all entities which use * it directly (e.g. nodes and guard conditions) or indirectly (e.g. * subscriptions and topics). */ typedef struct rcl_context_t { /// Global arguments for all nodes which share this context. - /** Typically generated by the parsing of argc/argv in `rcl_init()`. */ + /** Typically generated by the parsing of argc/argv in rcl_init(). */ rcl_arguments_t global_arguments; /// Implementation specific pointer. @@ -117,13 +122,15 @@ typedef struct rcl_context_t // The assumption that this is big enough for an atomic_uint_least64_t is // ensured with a static_assert in the context.c file. // In most cases it should just be a plain uint64_t. +/// @cond Doxygen_Suppress #if !defined(RCL_CONTEXT_ATOMIC_INSTANCE_ID_STORAGE_SIZE) #define RCL_CONTEXT_ATOMIC_INSTANCE_ID_STORAGE_SIZE sizeof(uint_least64_t) #endif +/// @endcond /// Private storage for instance ID atomic. /** * Accessing the instance id should be done using the function - * `rcl_context_get_instance_id()` because the instance id's type is an + * rcl_context_get_instance_id() because the instance id's type is an * atomic and needs to be accessed properly to ensure safety. * * The instance id should not be changed manually - doing so is undefined @@ -148,17 +155,15 @@ RCL_WARN_UNUSED rcl_context_t rcl_get_zero_initialized_context(void); -// See `rcl_init()` for initialization of the context. - /// Finalize a context. /** * The context to be finalized must have been previously initialized with - * `rcl_init()`, and then later invalidated with `rcl_shutdown()`. + * rcl_init(), and then later invalidated with rcl_shutdown(). * A zero-initialized context that has not been initialized can be finalized. - * If context is `NULL`, then `RCL_RET_INVALID_ARGUMENT` is returned. - * If context is zero-initialized, then `RCL_RET_OK` is returned. - * If context is initialized and valid (`rcl_shutdown()` was not called on it), - * then `RCL_RET_INVALID_ARGUMENT` is returned. + * If context is `NULL`, then #RCL_RET_INVALID_ARGUMENT is returned. + * If context is zero-initialized, then #RCL_RET_OK is returned. + * If context is initialized and valid (rcl_shutdown() was not called on it), + * then #RCL_RET_INVALID_ARGUMENT is returned. * *
* Attribute | Adherence @@ -170,17 +175,15 @@ rcl_get_zero_initialized_context(void); * [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. + * \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_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_context_fini(rcl_context_t * context); -// See `rcl_shutdown()` for invalidation of the context. - /// Return the init options used during initialization for this context. /** * This function can fail and return `NULL` if: @@ -220,7 +223,7 @@ rcl_context_get_init_options(const rcl_context_t * context); * If context is uninitialized, then it is undefined behavior. * * The instance ID may be `0` if the context is zero-initialized or if the - * context has been invalidated by `rcl_shutdown()`. + * context has been invalidated by rcl_shutdown(). * *
* Attribute | Adherence @@ -253,14 +256,14 @@ rcl_context_get_instance_id(const rcl_context_t * context); * Uses Atomics | No * Lock-Free | No * - * [1] Calling the function asynchronously with `rcl_init` or `rcl_shutdown` can result - * in the function sometimes succeeding and sometimes returning `RCL_RET_INVALID_ARGUMENT`. + * [1] Calling the function asynchronously with rcl_init() or rcl_shutdown() can result + * in the function sometimes succeeding and sometimes returning #RCL_RET_INVALID_ARGUMENT. * * \param[in] context from which the domain id should be retrieved. * \param[out] domain_id output variable where the domain id will be returned. - * \return RCL_RET_INVALID_ARGUMENT if `context` is invalid \ref `rcl_context_is_valid`, or - * \return RCL_RET_INVALID_ARGUMENT if `domain_id` is `NULL`, or - * \return RCL_RET_OK if the domain id was correctly retrieved. + * \return #RCL_RET_INVALID_ARGUMENT if `context` is invalid (see rcl_context_is_valid()), or + * \return #RCL_RET_INVALID_ARGUMENT if `domain_id` is `NULL`, or + * \return #RCL_RET_OK if the domain id was correctly retrieved. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/domain_id.h b/rcl/include/rcl/domain_id.h index 5cb696aec1..946c6830d6 100644 --- a/rcl/include/rcl/domain_id.h +++ b/rcl/include/rcl/domain_id.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__DOMAIN_ID_H_ #define RCL__DOMAIN_ID_H_ @@ -26,6 +28,7 @@ extern "C" #include "rcl/visibility_control.h" #include "rmw/domain_id.h" +/// The default domain ID used by RCL. #define RCL_DEFAULT_DOMAIN_ID RMW_DEFAULT_DOMAIN_ID extern const char * const RCL_DOMAIN_ID_ENV_VAR; @@ -33,9 +36,9 @@ extern const char * const RCL_DOMAIN_ID_ENV_VAR; /// Determine the default domain ID, based on the environment. /** * \param[out] domain_id Must not be NULL. - * \returns RCL_RET_INVALID_ARGUMENT if an argument is invalid, or, - * \returns RCL_RET_ERROR in case of an unexpected error, or, - * \returns RCL_RET_OK. + * \returns #RCL_RET_INVALID_ARGUMENT if an argument is invalid, or, + * \returns #RCL_RET_ERROR in case of an unexpected error, or, + * \returns #RCL_RET_OK. */ RCL_PUBLIC rcl_ret_t diff --git a/rcl/include/rcl/event.h b/rcl/include/rcl/event.h index 6798a9d5ea..a366dd45ba 100644 --- a/rcl/include/rcl/event.h +++ b/rcl/include/rcl/event.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__EVENT_H_ #define RCL__EVENT_H_ @@ -27,6 +29,7 @@ extern "C" #include "rcl/subscription.h" #include "rcl/visibility_control.h" +/// Enumeration of all of the publisher events that may fire. typedef enum rcl_publisher_event_type_t { RCL_PUBLISHER_OFFERED_DEADLINE_MISSED, @@ -34,6 +37,7 @@ typedef enum rcl_publisher_event_type_t RCL_PUBLISHER_OFFERED_INCOMPATIBLE_QOS, } rcl_publisher_event_type_t; +/// Enumeration of all of the subscription events that may fire. typedef enum rcl_subscription_event_type_t { RCL_SUBSCRIPTION_REQUESTED_DEADLINE_MISSED, @@ -59,6 +63,8 @@ typedef struct rcl_event_t /** * Should be called to get a null rcl_event_t before passing to * rcl_event_init(). + * + * \return Zero initialized rcl_event_t. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -72,11 +78,11 @@ rcl_get_zero_initialized_event(void); * \param[in,out] event pointer to fill * \param[in] publisher to get events from * \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. + * \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. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -93,11 +99,11 @@ rcl_publisher_event_init( * \param[in,out] event pointer to fill * \param[in] subscription to get events from * \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. + * \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. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -113,11 +119,11 @@ rcl_subscription_event_init( * * \param[in] event event object to take from * \param[in, out] event_info event info object to write taken data into - * \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. + * \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_WARN_UNUSED @@ -131,9 +137,9 @@ rcl_take_event( * Finalize an event. * * \param[in] event to finalize - * \return `RCL_RET_OK` if successful, or - * \return `RCL_RET_EVENT_INVALID` if event is null, or - * \return `RCL_RET_ERROR` if an unexpected error occurs. + * \return #RCL_RET_OK if successful, or + * \return #RCL_RET_EVENT_INVALID if event is null, or + * \return #RCL_RET_ERROR if an unexpected error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/expand_topic_name.h b/rcl/include/rcl/expand_topic_name.h index 4816cbfbeb..058e57e236 100644 --- a/rcl/include/rcl/expand_topic_name.h +++ b/rcl/include/rcl/expand_topic_name.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__EXPAND_TOPIC_NAME_H_ #define RCL__EXPAND_TOPIC_NAME_H_ @@ -102,14 +104,14 @@ extern "C" * \param[in] substitutions string map with possible substitutions * \param[in] allocator the allocator to be used when creating the output topic * \param[out] output_topic_name output char * pointer - * \return `RCL_RET_OK` if the topic name was expanded successfully, 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_TOPIC_NAME_INVALID` if the given topic name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the namespace_ is invalid, or - * \return `RCL_RET_UNKNOWN_SUBSTITUTION` for unknown substitutions in name, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the topic name was expanded successfully, 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_TOPIC_NAME_INVALID if the given topic name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the namespace_ is invalid, or + * \return #RCL_RET_UNKNOWN_SUBSTITUTION for unknown substitutions in name, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -127,10 +129,10 @@ rcl_expand_topic_name( * If the string map is not initialized RCL_RET_INVALID_ARGUMENT is returned. * * \param[inout] string_map rcutils_string_map_t map to be filled with pairs - * \return `RCL_RET_OK` if successfully, 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` if an unspecified error occurs. + * \return #RCL_RET_OK if successfully, 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 if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/graph.h b/rcl/include/rcl/graph.h index e4756937d5..9392573e1c 100644 --- a/rcl/include/rcl/graph.h +++ b/rcl/include/rcl/graph.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__GRAPH_H_ #define RCL__GRAPH_H_ @@ -33,13 +35,25 @@ extern "C" #include "rcl/node.h" #include "rcl/visibility_control.h" +/// A structure that contains topic names and types. typedef rmw_names_and_types_t rcl_names_and_types_t; + +/// A structure that encapsulates the node name, node namespace, +/// topic type, gid, and qos_profile or publishers and subscriptions +/// for a topic. typedef rmw_topic_endpoint_info_t rcl_topic_endpoint_info_t; + +/// An array of topic endpoint information. typedef rmw_topic_endpoint_info_array_t rcl_topic_endpoint_info_array_t; +/// Return a zero-initialized rcl_names_and_types_t structure. #define rcl_get_zero_initialized_names_and_types rmw_get_zero_initialized_names_and_types + +/// Return a zero-initialized rcl_topic_endpoint_info_t structure. #define rcl_get_zero_initialized_topic_endpoint_info_array \ rmw_get_zero_initialized_topic_endpoint_info_array + +/// Finalize a topic_endpoint_info_array_t structure. #define rcl_topic_endpoint_info_array_fini rmw_topic_endpoint_info_array_fini /// Return a list of topic names and types for publishers associated with a node. @@ -78,13 +92,13 @@ typedef rmw_topic_endpoint_info_array_t rcl_topic_endpoint_info_array_t; * \param[in] node_name the node name of the topics to return * \param[in] node_namespace the node namespace of the topics to return * \param[out] topic_names_and_types list of topic names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the node name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the node namespace is invalid, or - * \return `RCL_RET_NODE_NAME_NON_EXISTENT` if the node name wasn't found, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the node name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the node namespace is invalid, or + * \return #RCL_RET_NODE_NAME_NON_EXISTENT if the node name wasn't found, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -128,13 +142,13 @@ rcl_get_publisher_names_and_types_by_node( * \param[in] node_name the node name of the topics to return * \param[in] node_namespace the node namespace of the topics to return * \param[out] topic_names_and_types list of topic names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the node name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the node namespace is invalid, or - * \return `RCL_RET_NODE_NAME_NON_EXISTENT` if the node name wasn't found, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the node name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the node namespace is invalid, or + * \return #RCL_RET_NODE_NAME_NON_EXISTENT if the node name wasn't found, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -177,13 +191,13 @@ rcl_get_subscriber_names_and_types_by_node( * \param[in] node_name the node name of the services to return * \param[in] node_namespace the node namespace of the services to return * \param[out] service_names_and_types list of service names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the node name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the node namespace is invalid, or - * \return `RCL_RET_NODE_NAME_NON_EXISTENT` if the node name wasn't found, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the node name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the node namespace is invalid, or + * \return #RCL_RET_NODE_NAME_NON_EXISTENT if the node name wasn't found, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -225,13 +239,13 @@ rcl_get_service_names_and_types_by_node( * \param[in] node_name the node name of the services to return * \param[in] node_namespace the node namespace of the services to return * \param[out] service_names_and_types list of service client names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the node name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the node namespace is invalid, or - * \return `RCL_RET_NODE_NAME_NON_EXISTENT` if the node name wasn't found, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the node name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the node namespace is invalid, or + * \return #RCL_RET_NODE_NAME_NON_EXISTENT if the node name wasn't found, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -272,12 +286,12 @@ rcl_get_client_names_and_types_by_node( * \param[in] allocator allocator to be used when allocating space for strings * \param[in] no_demangle if true, list all topics without any demangling * \param[out] topic_names_and_types list of topic names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_NODE_INVALID_NAME` if the node name is invalid, or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the node namespace is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_NODE_INVALID_NAME if the node name is invalid, or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the node namespace is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -314,10 +328,10 @@ rcl_get_topic_names_and_types( * \param[in] node the handle to the node being used to query the ROS graph * \param[in] allocator allocator to be used when allocating space for strings * \param[out] service_names_and_types list of service names and their types - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -345,10 +359,10 @@ rcl_get_service_names_and_types( * \param[inout] names_and_types object to be initialized * \param[in] size the number of names and sets of types to be stored * \param[in] allocator to be used to allocate and deallocate memory - * \returns `RCL_RET_OK` on success, or - * \returns `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \returns `RCL_BAD_ALLOC` if memory allocation fails, or - * \returns `RCL_RET_ERROR` when an unspecified error occurs. + * \return #RCL_RET_OK on success, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if memory allocation fails, or + * \return #RCL_RET_ERROR when an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -377,9 +391,9 @@ rcl_names_and_types_init( * Lock-Free | Yes * * \param[inout] names_and_types struct to be finalized - * \return `RCL_RET_OK` if successful, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if successful, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -428,10 +442,10 @@ rcl_names_and_types_fini(rcl_names_and_types_t * names_and_types); * \param[in] allocator used to control allocation and deallocation of names * \param[out] node_names struct storing discovered node names * \param[out] node_namespaces 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. + * \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_WARN_UNUSED @@ -444,7 +458,7 @@ rcl_get_node_names( /// Return a list of available nodes in the ROS graph, including their enclave names. /** - * An \ref rcl_get_node_names equivalent, but including in its output the enclave + * An rcl_get_node_names() equivalent, but including in its output the enclave * name the node is using. * *
@@ -461,10 +475,10 @@ rcl_get_node_names( * \param[out] node_names struct storing discovered node names * \param[out] node_namespaces struct storing discovered node namespaces * \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. + * \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_WARN_UNUSED @@ -508,10 +522,10 @@ rcl_get_node_names_with_enclaves( * \param[in] node the handle to the node being used to query the ROS graph * \param[in] topic_name the name of the topic in question * \param[out] count number of publishers on the given topic - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -553,10 +567,10 @@ rcl_count_publishers( * \param[in] node the handle to the node being used to query the ROS graph * \param[in] topic_name the name of the topic in question * \param[out] count number of subscriptions on the given topic - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -611,11 +625,11 @@ rcl_count_subscribers( * \param[in] no_mangle if `true`, `topic_name` needs to be a valid middleware topic name, * otherwise it should be a valid ROS topic name * \param[out] publishers_info a struct representing a list of publisher information - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if memory allocation fails, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if memory allocation fails, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -672,11 +686,11 @@ rcl_get_publishers_info_by_topic( * \param[in] no_mangle if `true`, `topic_name` needs to be a valid middleware topic name, * otherwise it should be a valid ROS topic name * \param[out] subscriptions_info a struct representing a list of subscriptions information - * \return `RCL_RET_OK` if the query was successful, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if memory allocation fails, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the query was successful, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if memory allocation fails, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -718,10 +732,10 @@ rcl_get_subscriptions_info_by_topic( * \param[in] node the handle to the node being used to query the ROS graph * \param[in] client the handle to the service client being queried * \param[out] is_available set to true if there is a service server available, else false - * \return `RCL_RET_OK` if the check was made successfully (regardless of the service readiness), or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the check was made successfully (regardless of the service readiness), or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/guard_condition.h b/rcl/include/rcl/guard_condition.h index 9f40ccd6cb..a6727d3a2d 100644 --- a/rcl/include/rcl/guard_condition.h +++ b/rcl/include/rcl/guard_condition.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__GUARD_CONDITION_H_ #define RCL__GUARD_CONDITION_H_ @@ -84,12 +86,12 @@ rcl_get_zero_initialized_guard_condition(void); * \param[in] context the context instance with which the guard condition * should be associated * \param[in] options the guard_condition's options - * \return `RCL_RET_OK` if guard_condition was initialized successfully, or - * \return `RCL_RET_ALREADY_INIT` if the guard condition is already 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_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if guard_condition was initialized successfully, or + * \return #RCL_RET_ALREADY_INIT if the guard condition is already 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_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -127,11 +129,11 @@ rcl_guard_condition_init( * was initialized with, i.e. the rmw context inside rcl context needs to * match rmw context in rmw guard condition * \param[in] options the guard_condition's options - * \return `RCL_RET_OK` if guard_condition was initialized successfully, or - * \return `RCL_RET_ALREADY_INIT` if the guard condition is already 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` if an unspecified error occurs. + * \return #RCL_RET_OK if guard_condition was initialized successfully, or + * \return #RCL_RET_ALREADY_INIT if the guard condition is already 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 if an unspecified error occurs. */ rcl_ret_t rcl_guard_condition_init_from_rmw( @@ -155,9 +157,9 @@ rcl_guard_condition_init_from_rmw( * [1] specifically not thread-safe with rcl_trigger_guard_condition() * * \param[inout] guard_condition handle to the guard_condition to be finalized - * \return `RCL_RET_OK` if guard_condition was finalized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if guard_condition was finalized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -169,6 +171,8 @@ rcl_guard_condition_fini(rcl_guard_condition_t * guard_condition); * The defaults are: * * - allocator = rcl_get_default_allocator() + * + * \return the default options in an rcl_guard_condition_options_t struct. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -193,9 +197,9 @@ rcl_guard_condition_get_default_options(void); * [1] it can be called concurrently with itself, even on the same guard condition * * \param[in] guard_condition handle to the guard_condition to be triggered - * \return `RCL_RET_OK` if the guard condition was triggered, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the guard condition was triggered, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/init.h b/rcl/include/rcl/init.h index 42b07b5f0c..a85aae609c 100644 --- a/rcl/include/rcl/init.h +++ b/rcl/include/rcl/init.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__INIT_H_ #define RCL__INIT_H_ @@ -32,14 +34,14 @@ extern "C" * This function can be run any number of times, so long as the given context * has been properly prepared. * - * The given `rcl_context_t` must be zero initialized with the function - * `rcl_get_zero_initialized_context()` and must not be already initialized + * The given rcl_context_t must be zero initialized with the function + * rcl_get_zero_initialized_context() and must not be already initialized * by this function. * If the context is already initialized this function will fail and return the - * `RCL_RET_ALREADY_INIT` error code. + * #RCL_RET_ALREADY_INIT error code. * A context may be initialized again after it has been finalized with the - * `rcl_shutdown()` function and zero initialized again with - * `rcl_get_zero_initialized_context()`. + * rcl_shutdown() function and zero initialized again with + * rcl_get_zero_initialized_context(). * * The `argc` and `argv` parameters may contain command line arguments for the * program. @@ -47,11 +49,11 @@ extern "C" * If `argc` is `0` and `argv` is `NULL` no parameters will be parsed. * * The `options` argument must be non-`NULL` and must have been initialized - * with `rcl_init_options_init()`. + * with rcl_init_options_init(). * It is unmodified by this function, and the ownership is not transfered to * the context, but instead a copy is made into the context for later reference. * Therefore, the given options need to be cleaned up with - * `rcl_init_options_fini()` after this function returns. + * rcl_init_options_fini() after this function returns. * *
* Attribute | Adherence @@ -66,12 +68,12 @@ extern "C" * \param[in] argv command line arguments; rcl specific arguments are removed * \param[in] options options used during initialization * \param[out] context resulting context object that represents this init - * \return `RCL_RET_OK` if initialization is successful, or - * \return `RCL_RET_ALREADY_INIT` if rcl_init has already been called, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_INVALID_ROS_ARGS` if an invalid ROS argument is found, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if initialization is successful, or + * \return #RCL_RET_ALREADY_INIT if rcl_init has already been called, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_INVALID_ROS_ARGS if an invalid ROS argument is found, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -84,13 +86,13 @@ rcl_init( /// Shutdown a given rcl context. /** - * The given context must have been initialized with `rcl_init()`. - * If not, this function will fail with `RCL_RET_ALREADY_SHUTDOWN`. + * The given context must have been initialized with rcl_init(). + * If not, this function will fail with #RCL_RET_ALREADY_SHUTDOWN. * * When this function is called: * - Any rcl objects created using this context are invalidated. * - Functions called on invalid objects may or may not fail. - * - Calls to `rcl_context_is_initialized()` will return `false`. + * - Calls to rcl_context_is_initialized() will return `false`. * *
* Attribute | Adherence @@ -102,10 +104,10 @@ rcl_init( * [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 - * \return `RCL_RET_ERROR` if an unspecified error occur. + * \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 + * \return #RCL_RET_ERROR if an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/init_options.h b/rcl/include/rcl/init_options.h index 1b97b82ac2..a72bf13336 100644 --- a/rcl/include/rcl/init_options.h +++ b/rcl/include/rcl/init_options.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__INIT_OPTIONS_H_ #define RCL__INIT_OPTIONS_H_ @@ -61,11 +63,11 @@ rcl_get_zero_initialized_init_options(void); * * \param[inout] init_options object to be setup * \param[in] allocator to be used during setup and during initialization - * \return `RCL_RET_OK` if setup is successful, or - * \return `RCL_RET_ALREADY_INIT` if init_options has already be 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` if an unspecified error occurs. + * \return #RCL_RET_OK if setup is successful, or + * \return #RCL_RET_ALREADY_INIT if init_options has already be 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 if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -78,10 +80,10 @@ rcl_init_options_init(rcl_init_options_t * init_options, rcl_allocator_t allocat * destination. * * The destination should either be zero initialized with - * `rcl_get_zero_initialized_init_options()` or should have had - * `rcl_init_options_fini()` called on it. + * rcl_get_zero_initialized_init_options() or should have had + * rcl_init_options_fini() called on it. * Giving an already initialized init options for the destination will result - * in a failure with return code `RCL_RET_ALREADY_INIT`. + * in a failure with return code #RCL_RET_ALREADY_INIT. * *
* Attribute | Adherence @@ -93,11 +95,11 @@ rcl_init_options_init(rcl_init_options_t * init_options, rcl_allocator_t allocat * * \param[in] src rcl_init_options_t object to be copied from * \param[out] dst rcl_init_options_t object to be copied into - * \return `RCL_RET_OK` if the copy is successful, or - * \return `RCL_RET_ALREADY_INIT` if the dst has already be 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` if an unspecified error occurs. + * \return #RCL_RET_OK if the copy is successful, or + * \return #RCL_RET_ALREADY_INIT if the dst has already be 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 if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -107,7 +109,7 @@ rcl_init_options_copy(const rcl_init_options_t * src, rcl_init_options_t * dst); /// Finalize the given init_options. /** * The given init_options must be non-`NULL` and valid, i.e. had - * `rcl_init_options_init()` called on it but not this function yet. + * rcl_init_options_init() called on it but not this function yet. * *
* Attribute | Adherence @@ -118,9 +120,9 @@ rcl_init_options_copy(const rcl_init_options_t * src, rcl_init_options_t * dst); * Lock-Free | Yes * * \param[inout] init_options object to be setup - * \return `RCL_RET_OK` if setup is successful, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if setup is successful, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -141,8 +143,8 @@ rcl_init_options_fini(rcl_init_options_t * init_options); * * \param[in] init_options object from which the domain id should be retrieved. * \param[out] domain_id domain id to be set in init_options object. - * \return `RCL_RET_OK` if successful, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid. + * \return #RCL_RET_OK if successful, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -163,8 +165,8 @@ rcl_init_options_get_domain_id(const rcl_init_options_t * init_options, size_t * * * \param[in] init_options objects in which to set the specified domain id. * \param[in] domain_id domain id to be set in init_options object. - * \return `RCL_RET_OK` if successful, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid. + * \return #RCL_RET_OK if successful, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/lexer.h b/rcl/include/rcl/lexer.h index 032bf8c881..7d652def57 100644 --- a/rcl/include/rcl/lexer.h +++ b/rcl/include/rcl/lexer.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LEXER_H_ #define RCL__LEXER_H_ @@ -76,7 +78,7 @@ typedef enum rcl_lexeme_t RCL_LEXEME_WILD_MULTI = 21, // TODO(hidmic): remove when parameter names are standardized to // use slashes in lieu of dots - /// . + /// \. RCL_LEXEME_DOT = 22, } rcl_lexeme_t; @@ -99,9 +101,9 @@ typedef enum rcl_lexeme_t * \param[in] text The string to analyze. * \param[out] lexeme The type of lexeme found in the string. * \param[out] length The length of text in the string that constitutes the found lexeme. - * \return `RCL_RET_OK` if analysis is successful regardless whether a valid lexeme is found, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an internal bug is detected. + * \return #RCL_RET_OK if analysis is successful regardless whether a valid lexeme is found, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an internal bug is detected. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/lexer_lookahead.h b/rcl/include/rcl/lexer_lookahead.h index d50166e3f9..79fe9b9588 100644 --- a/rcl/include/rcl/lexer_lookahead.h +++ b/rcl/include/rcl/lexer_lookahead.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LEXER_LOOKAHEAD_H_ #define RCL__LEXER_LOOKAHEAD_H_ @@ -75,10 +77,10 @@ rcl_get_zero_initialized_lexer_lookahead2(); * \sa rcl_get_zero_initialized_lexer_lookahead2() * \param[in] text The string to analyze. * \param[in] allocator An allocator to use if an error occurs. - * \return `RCL_RET_OK` if the buffer is successfully initialized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurrs. + * \return #RCL_RET_OK if the buffer is successfully initialized, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurrs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -102,9 +104,9 @@ rcl_lexer_lookahead2_init( * [1] Only allocates if an argument is invalid. * * \param[in] buffer The structure to be deallocated. - * \return `RCL_RET_OK` if the structure was successfully finalized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the structure was successfully finalized, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -129,9 +131,9 @@ rcl_lexer_lookahead2_fini( * * \param[in] buffer the lookahead2 buffer being used to analyze a string. * \param[out] next_type an output variable for the next lexeme in the string. - * \return `RCL_RET_OK` if peeking was successfull, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if peeking was successfull, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -158,9 +160,9 @@ rcl_lexer_lookahead2_peek( * \param[in] buffer the lookahead2 buffer being used to analyze a string. * \param[out] next_type1 an output variable for the next lexeme in the string. * \param[out] next_type2 an output variable for the lexeme after the next lexeme in the string. - * \return `RCL_RET_OK` if peeking was successfull, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if peeking was successfull, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -188,9 +190,9 @@ rcl_lexer_lookahead2_peek2( * \param[in] buffer the lookahead2 buffer being used to analyze a string. * \param[out] lexeme_text pointer to where lexeme begins in string. * \param[out] lexeme_text_length length of lexeme_text. - * \return `RCL_RET_OK` if peeking was successfull, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if peeking was successfull, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -220,10 +222,10 @@ rcl_lexer_lookahead2_accept( * \param[in] type the type the next lexeme must be. * \param[out] lexeme_text pointer to where lexeme begins in string. * \param[out] lexeme_text_length length of lexeme_text. - * \return `RCL_RET_OK` if the next lexeme was the expected one, or - * \return `RCL_RET_WRONG_LEXEME` if the next lexeme was not the expected one, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the next lexeme was the expected one, or + * \return #RCL_RET_WRONG_LEXEME if the next lexeme was not the expected one, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/localhost.h b/rcl/include/rcl/localhost.h index 551b367024..2c5123a59e 100644 --- a/rcl/include/rcl/localhost.h +++ b/rcl/include/rcl/localhost.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LOCALHOST_H_ #define RCL__LOCALHOST_H_ @@ -31,9 +33,9 @@ extern const char * const RCL_LOCALHOST_ENV_VAR; * Checks if localhost should be used for network communication based on environment. * * \param[out] localhost_only Must not be NULL. - * \returns RCL_RET_INVALID_ARGUMENT if an argument is invalid, or - * \returns RCL_RET_ERROR if an unexpected error happened, or - * \returns RCL_RET_OK. + * \return #RCL_RET_INVALID_ARGUMENT if an argument is invalid, or + * \return #RCL_RET_ERROR if an unexpected error happened, or + * \return #RCL_RET_OK. */ RCL_PUBLIC rcl_ret_t diff --git a/rcl/include/rcl/log_level.h b/rcl/include/rcl/log_level.h index 14a8ead5d3..a907ad8ba3 100644 --- a/rcl/include/rcl/log_level.h +++ b/rcl/include/rcl/log_level.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LOG_LEVEL_H_ #define RCL__LOG_LEVEL_H_ @@ -83,11 +85,11 @@ rcl_get_zero_initialized_log_levels(); * \param[in] allocator Memory allocator to be used and assigned into log_levels. * \param[in] logger_count Number of logger settings to be allocated. * This reserves memory for logger_settings, but doesn't initialize it. - * \return `RCL_RET_OK` if the structure was initialized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or - * log_levels contains initialized memory, or - * allocator is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed. + * \return #RCL_RET_OK if the structure was initialized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels is NULL, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels contains initialized memory, or + * \return #RCL_RET_INVALID_ARGUMENT if allocator is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -108,12 +110,12 @@ rcl_log_levels_init( * \param[in] src The structure to be copied. * Its allocator is used to copy memory into the new structure. * \param[out] dst A log levels structure to be copied into. - * \return `RCL_RET_OK` if the structure was copied successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if src is NULL, or - * if src allocator is invalid, or - * if dst is NULL, or - * if dst contains already allocated memory, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed. + * \return #RCL_RET_OK if the structure was copied successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if src is NULL, or + * \return #RCL_RET_INVALID_ARGUMENT if src allocator is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if dst is NULL, or + * \return #RCL_RET_INVALID_ARGUMENT if dst contains already allocated memory, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -131,9 +133,9 @@ rcl_log_levels_copy(const rcl_log_levels_t * src, rcl_log_levels_t * dst); * Lock-Free | Yes * * \param[in] log_levels The structure which its resources have to be deallocated. - * \return `RCL_RET_OK` if the memory was successfully freed, or - * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or - * if ist allocator is invalid and the structure contains initialized memory. + * \return #RCL_RET_OK if the memory was successfully freed, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels is NULL, or + * \return #RCL_RET_INVALID_ARGUMENT if the log_levels allocator is invalid and the structure contains initialized memory. */ RCL_PUBLIC rcl_ret_t @@ -150,9 +152,9 @@ rcl_log_levels_fini(rcl_log_levels_t * log_levels); * Lock-Free | Yes * * \param[in] log_levels The structure to be shrunk. - * \return `RCL_RET_OK` if the memory was successfully shrunk, or - * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL or if its allocator is invalid, or - * \return `RCL_RET_BAD_ALLOC` if reallocating memory failed. + * \return #RCL_RET_OK if the memory was successfully shrunk, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels is NULL or if its allocator is invalid, or + * \return #RCL_RET_BAD_ALLOC if reallocating memory failed. */ RCL_PUBLIC rcl_ret_t @@ -171,13 +173,13 @@ rcl_log_levels_shrink_to_size(rcl_log_levels_t * log_levels); * \param[in] log_levels The structure where to set the logger log level. * \param[in] logger_name Name for the logger, a copy of it will be stored in the structure. * \param[in] log_level Minimum log level severity to be set for logger_name. - * \return `RCL_RET_OK` if add logger setting successfully, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_INVALID_ARGUMENT` if log_levels is NULL, or - * if log_levels was not initialized, or - * if log_levels allocator is invalid, or - * if logger_name is NULL, or - * \return `RCL_RET_ERROR` if the log_levels structure is already full. + * \return #RCL_RET_OK if add logger setting successfully, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels is NULL, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels was not initialized, or + * \return #RCL_RET_INVALID_ARGUMENT if log_levels allocator is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if logger_name is NULL, or + * \return #RCL_RET_ERROR if the log_levels structure is already full. */ RCL_PUBLIC rcl_ret_t diff --git a/rcl/include/rcl/logging.h b/rcl/include/rcl/logging.h index 1014853d53..7b70b6977b 100644 --- a/rcl/include/rcl/logging.h +++ b/rcl/include/rcl/logging.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LOGGING_H_ #define RCL__LOGGING_H_ @@ -28,6 +30,7 @@ extern "C" { #endif +/// The function signature to log messages. typedef rcutils_logging_output_handler_t rcl_logging_output_handler_t; /// Configure the logging system. @@ -43,12 +46,12 @@ typedef rcutils_logging_output_handler_t rcl_logging_output_handler_t; * Uses Atomics | No * Lock-Free | Yes * - * \param global_args The global arguments for the system - * \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_ERROR` if a general error occurs + * \param[in] global_args The global arguments for the system + * \param[in] 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_ERROR if a general error occurs */ RCL_PUBLIC RCL_WARN_UNUSED @@ -70,13 +73,13 @@ rcl_logging_configure( * Uses Atomics | No * Lock-Free | Yes * - * \param global_args The global arguments for the system - * \param allocator Used to allocate memory used by the logging system - * \param output_handler Output handler to be installed - * \return `RCL_RET_OK` if successful, 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` if a general error occurs + * \param[in] global_args The global arguments for the system + * \param[in] allocator Used to allocate memory used by the logging system + * \param[in] output_handler Output handler to be installed + * \return #RCL_RET_OK if successful, 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 if a general error occurs */ RCL_PUBLIC RCL_WARN_UNUSED @@ -97,8 +100,8 @@ rcl_logging_configure_with_output_handler( * Uses Atomics | No * Lock-Free | Yes * - * \return `RCL_RET_OK` if successful. - * \return `RCL_RET_ERROR` if a general error occurs + * \return #RCL_RET_OK if successful. + * \return #RCL_RET_ERROR if a general error occurs */ RCL_PUBLIC RCL_WARN_UNUSED @@ -127,8 +130,8 @@ bool rcl_logging_rosout_enabled(); /** * This function can be wrapped in a language specific client library, * adding the necessary mutual exclusion protection there, and then use - * `rcl_logging_configure_with_output_handler` instead of - * `rcl_logging_configure`. + * rcl_logging_configure_with_output_handler() instead of + * rcl_logging_configure(). * *
* Attribute | Adherence @@ -137,6 +140,13 @@ bool rcl_logging_rosout_enabled(); * Thread-Safe | Yes * Uses Atomics | No * Lock-Free | Yes + * + * \param[in] location The pointer to the location struct or NULL + * \param[in] severity The severity level + * \param[in] name The name of the logger, must be null terminated c string + * \param[in] timestamp The timestamp for when the log message was made + * \param[in] format The list of arguments to insert into the formatted log message + * \param[in] args argument for the string format */ RCL_PUBLIC void diff --git a/rcl/include/rcl/logging_rosout.h b/rcl/include/rcl/logging_rosout.h index 087e981cf8..5bbac1bdf4 100644 --- a/rcl/include/rcl/logging_rosout.h +++ b/rcl/include/rcl/logging_rosout.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__LOGGING_ROSOUT_H_ #define RCL__LOGGING_ROSOUT_H_ @@ -59,10 +61,10 @@ static const rmw_qos_profile_t rcl_qos_profile_rosout_default = * Lock-Free | Yes * * \param[in] allocator The allocator used for metadata related to the rcl_logging_rosout features - * \return `RCL_RET_OK` if the rcl_logging_rosout features are 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` if an unspecified error occurs. + * \return #RCL_RET_OK if the rcl_logging_rosout features are 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 if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -83,8 +85,8 @@ rcl_logging_rosout_init( * Uses Atomics | No * Lock-Free | Yes * - * \return `RCL_RET_OK` if the rcl_logging_rosout feature was successfully unitialized, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the rcl_logging_rosout feature was successfully unitialized, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -112,10 +114,10 @@ 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 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. + * \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. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -138,10 +140,10 @@ 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 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. + * \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_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/node.h b/rcl/include/rcl/node.h index 011347fd35..c21378aa0d 100644 --- a/rcl/include/rcl/node.h +++ b/rcl/include/rcl/node.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__NODE_H_ #define RCL__NODE_H_ @@ -60,7 +62,7 @@ rcl_get_zero_initialized_node(void); * The name of the node must not be NULL and adhere to naming restrictions, * see the rmw_validate_node_name() function for rules. * - * \todo TODO(wjwwood): node name uniqueness is no yet enforced + * \todo TODO(wjwwood): node name uniqueness is not yet enforced * * The name of the node cannot coincide with another node of the same name. * If a node of the same name is already in the domain, it will be shutdown. @@ -130,14 +132,14 @@ rcl_get_zero_initialized_node(void); * The options are deep copied into the node. * The caller is always responsible for freeing memory used options they * 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 - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the namespace_ is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \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 + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the namespace_ is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -172,9 +174,9 @@ rcl_node_init( * [1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t` * * \param[in] node rcl_node_t to be finalized - * \return `RCL_RET_OK` if node was finalized successfully, or - * \return `RCL_RET_NODE_INVALID` if the node pointer is null, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if node was finalized successfully, or + * \return #RCL_RET_NODE_INVALID if the node pointer is null, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -343,7 +345,7 @@ rcl_node_get_options(const rcl_node_t * node); * * This function should be used to determine what `domain_id` was used rather * than checking the domain_id field in the node options, because if - * `RCL_NODE_OPTIONS_DEFAULT_DOMAIN_ID` is used when creating the node then + * #RCL_NODE_OPTIONS_DEFAULT_DOMAIN_ID is used when creating the node then * it is not changed after creation, but this function will return the actual * `domain_id` used. * @@ -360,10 +362,10 @@ rcl_node_get_options(const rcl_node_t * node); * * \param[in] node the handle to the node being queried * \param[out] domain_id storage for the domain id - * \return `RCL_RET_OK` if node the domain ID was retrieved successfully, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if node the domain ID was retrieved successfully, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -506,19 +508,19 @@ rcl_node_get_logger_name(const rcl_node_t * node); * \param[in] is_service For services use `true`, for topics use `false`. * \param[in] only_expand When `true`, remapping rules are ignored. * \param[out] output_name Output char * pointer. - * \return `RCL_RET_OK` if the topic name was expanded successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any of input_name, node_name, node_namespace + * \return #RCL_RET_OK if the topic name was expanded successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any of input_name, node_name, node_namespace * or output_name are NULL, or - * \return `RCL_RET_INVALID_ARGUMENT` if both local_args and global_args are NULL, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_TOPIC_NAME_INVALID` if the given topic name is invalid - * (see \ref rcl_validate_topic_name()), or - * \return `RCL_RET_NODE_INVALID_NAME` if the given node name is invalid - * (see \ref rmw_validate_node_name()), or - * \return `RCL_RET_NODE_INVALID_NAMESPACE` if the given node namespace is invalid - * (see \ref rmw_validate_namespace()), or - * \return `RCL_RET_UNKNOWN_SUBSTITUTION` for unknown substitutions in name, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_INVALID_ARGUMENT if both local_args and global_args are NULL, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_TOPIC_NAME_INVALID if the given topic name is invalid + * (see rcl_validate_topic_name()), or + * \return #RCL_RET_NODE_INVALID_NAME if the given node name is invalid + * (see rmw_validate_node_name()), or + * \return #RCL_RET_NODE_INVALID_NAMESPACE if the given node namespace is invalid + * (see rmw_validate_namespace()), or + * \return #RCL_RET_UNKNOWN_SUBSTITUTION for unknown substitutions in name, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/node_options.h b/rcl/include/rcl/node_options.h index acb3f1a746..0da2b0641a 100644 --- a/rcl/include/rcl/node_options.h +++ b/rcl/include/rcl/node_options.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__NODE_OPTIONS_H_ #define RCL__NODE_OPTIONS_H_ @@ -63,6 +65,8 @@ typedef struct rcl_node_options_t * - enable_rosout = true * - arguments = rcl_get_zero_initialized_arguments() * - rosout_qos = rcl_qos_profile_rosout_default + * + * \return A structure with the default node options. */ RCL_PUBLIC rcl_node_options_t @@ -81,10 +85,10 @@ rcl_node_get_default_options(void); * \param[in] options The structure to be copied. * Its allocator is used to copy memory into the new structure. * \param[out] options_out An options structure containing default values. - * \return `RCL_RET_OK` if the structure was copied successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the structure was copied successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -96,7 +100,7 @@ rcl_node_options_copy( /// Finalize the given node_options. /** * The given node_options must be non-`NULL` and valid, i.e. had - * `rcl_node_get_default_options()` called on it but not this function yet. + * rcl_node_get_default_options() called on it but not this function yet. * *
* Attribute | Adherence @@ -107,9 +111,9 @@ rcl_node_options_copy( * Lock-Free | Yes * * \param[inout] options object to be finalized - * \return `RCL_RET_OK` if setup is successful, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if setup is successful, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/publisher.h b/rcl/include/rcl/publisher.h index 3c274d95a7..85e26bfd55 100644 --- a/rcl/include/rcl/publisher.h +++ b/rcl/include/rcl/publisher.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__PUBLISHER_H_ #define RCL__PUBLISHER_H_ @@ -137,13 +139,13 @@ rcl_get_zero_initialized_publisher(void); * \param[in] type_support type support object for the topic's type * \param[in] topic_name the name of the topic to publish on * \param[in] options publisher options, including quality of service settings - * \return `RCL_RET_OK` if the publisher was initialized successfully, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ALREADY_INIT` if the publisher is already initialized, 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_TOPIC_NAME_INVALID` if the given topic name is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the publisher was initialized successfully, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ALREADY_INIT if the publisher is already initialized, 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_TOPIC_NAME_INVALID if the given topic name is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -173,11 +175,11 @@ rcl_publisher_init( * * \param[inout] publisher handle to the publisher to be finalized * \param[in] node a valid (not finalized) handle to the node used to create the publisher - * \return `RCL_RET_OK` if publisher was finalized successfully, 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_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if publisher was finalized successfully, 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_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -191,6 +193,8 @@ 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() + * + * \return A structure with the default publisher options. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -215,11 +219,12 @@ rcl_publisher_get_default_options(void); * \param[in] publisher Publisher to which the allocated message is associated. * \param[in] type_support Typesupport to which the internal ros message is allocated. * \param[out] ros_message The pointer to be filled to a valid ros message by the middleware. - * \return `RCL_RET_OK` if the ros message was correctly initialized, or - * \return `RCL_RET_INVALID_ARGUMENT` if an argument other than the ros message is null, or - * \return `RCL_RET_BAD_ALLOC` if the ros message could not be correctly created, or - * \return `RCL_RET_UNIMPLEMENTED` if the middleware does not support that feature, or - * \return `RCL_RET_ERROR` if an unexpected error occured. + * \return #RCL_RET_OK if the ros message was correctly initialized, or + * \return #RCL_RET_PUBLISHER_INVALID if the passed publisher is invalid, or + * \return #RCL_RET_INVALID_ARGUMENT if an argument other than the ros message is null, or + * \return #RCL_RET_BAD_ALLOC if the ros message could not be correctly created, or + * \return #RCL_RET_UNSUPPORTED if the middleware does not support that feature, or + * \return #RCL_RET_ERROR if an unexpected error occured. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -245,11 +250,11 @@ rcl_borrow_loaned_message( * * \param[in] publisher Publisher to which the loaned message is associated. * \param[in] loaned_message Loaned message to be deallocated and destroyed. - * \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. + * \return #RCL_RET_OK if successful, or + * \return #RCL_RET_INVALID_ARGUMENT if an argument is null, or + * \return #RCL_RET_UNSUPPORTED 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 RCL_WARN_UNUSED @@ -310,10 +315,10 @@ rcl_return_loaned_message_from_publisher( * \param[in] publisher handle to the publisher which will do the publishing * \param[in] ros_message type-erased pointer to the ROS message * \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_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. + * \return #RCL_RET_OK if the message was published successfully, 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. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -334,7 +339,7 @@ rcl_publish( * The publish call might be able to send any abitrary serialized message, it is however * not garantueed that the subscriber side successfully deserializes this byte stream. * - * Apart from this, the `publish_serialized` function has the same behavior as `rcl_publish` + * Apart from this, the `publish_serialized` function has the same behavior as rcl_publish() * expect that no serialization step is done. * *
@@ -349,11 +354,11 @@ rcl_publish( * \param[in] publisher handle to the publisher which will do the publishing * \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. + * \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. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -365,15 +370,15 @@ rcl_publish_serialized_message( /// Publish a loaned message on a topic using a publisher. /** - * A previously borrowed loaned message can be sent via this call to `rcl_publish_loaned_message`. + * A previously borrowed loaned message can be sent via this call to rcl_publish_loaned_message(). * By calling this function, the ownership of the loaned message is getting transferred back * to the middleware. * The pointer to the `ros_message` is not guaranteed to be valid after as the middleware * migth deallocate the memory for this message internally. * It is thus recommended to call this function only in combination with - * \sa `rcl_borrow_loaned_message`. + * \sa rcl_borrow_loaned_message(). * - * Apart from this, the `publish_loaned_message` function has the same behavior as `rcl_publish` + * Apart from this, the `publish_loaned_message` function has the same behavior as rcl_publish() * except that no serialization step is done. * *
@@ -390,11 +395,11 @@ rcl_publish_serialized_message( * \param[in] publisher handle to the publisher which will do the publishing * \param[in] ros_message pointer to the previously borrow loaned message * \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_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_PUBLISHER_INVALID` if the publisher is invalid, or - * \return `RCL_RET_UNIMPLEMENTED` if the middleware does not support that feature, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the message was published successfully, 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_UNSUPPORTED if the middleware does not support that feature, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -420,9 +425,9 @@ rcl_publish_loaned_message( * Lock-Free | Yes * * \param[in] publisher handle to the publisher that needs liveliness to be asserted - * \return `RCL_RET_OK` if the liveliness assertion was completed successfully, or - * \return `RCL_RET_PUBLISHER_INVALID` if the publisher is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the liveliness assertion was completed successfully, or + * \return #RCL_RET_PUBLISHER_INVALID if the publisher is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -592,10 +597,10 @@ rcl_publisher_is_valid_except_context(const rcl_publisher_t * publisher); * * \param[in] publisher pointer to the rcl publisher * \param[out] subscription_count number of matched subscriptions - * \return `RCL_RET_OK` if the count was retrieved, 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. + * \return #RCL_RET_OK if the count was retrieved, 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. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/remap.h b/rcl/include/rcl/remap.h index 82f0b0e041..4de969cf28 100644 --- a/rcl/include/rcl/remap.h +++ b/rcl/include/rcl/remap.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__REMAP_H_ #define RCL__REMAP_H_ @@ -53,12 +55,12 @@ rcl_get_zero_initialized_remap(void); * If both `local_arguments` and global_arguments are NULL or zero intialized then the function will * return RCL_RET_INVALID_ARGUMENT. * - * `global_arguments` is usually the arguments passed to `rcl_init()`. + * `global_arguments` is usually the arguments passed to rcl_init(). * \sa rcl_init() * \sa rcl_get_global_arguments() * * Remap rules are checked in the order they were given. - * For rules passed to `rcl_init` this usually is the order they were passed on the command line. + * For rules passed to rcl_ini()` this usually is the order they were passed on the command line. * \sa rcl_parse_arguments() * * Only the first remap rule that matches is used to remap a name. @@ -98,11 +100,11 @@ rcl_get_zero_initialized_remap(void); * \param[in] allocator A valid allocator to use. * \param[out] output_name Either an allocated string with the remapped name, or * `NULL` if no remap rules matched the name. - * \return `RCL_RET_OK` if the topic name was remapped or no rules matched, 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_TOPIC_NAME_INVALID` if the given topic name is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the topic name was remapped or no rules matched, 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_TOPIC_NAME_INVALID if the given topic name is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -143,11 +145,11 @@ rcl_remap_topic_name( * \param[in] allocator A valid allocator to use. * \param[out] output_name Either an allocated string with the remapped name, or * `NULL` if no remap rules matched the name. - * \return `RCL_RET_OK` if the name was remapped or no rules matched, 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_SERVICE_NAME_INVALID` if the given name is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the name was remapped or no rules matched, 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_SERVICE_NAME_INVALID if the given name is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -190,11 +192,11 @@ rcl_remap_service_name( * \param[in] allocator A valid allocator to use. * \param[out] output_name Either an allocated string with the remapped name, or * `NULL` if no remap rules matched the name. - * \return `RCL_RET_OK` If the name was remapped or no rules matched, 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 - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK If the name was remapped or no rules matched, 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 + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -231,11 +233,11 @@ rcl_remap_node_name( * \param[in] allocator A valid allocator to be used. * \param[out] output_namespace Either an allocated string with the remapped namespace, or * `NULL` if no remap rules matched the name. - * \return `RCL_RET_OK` if the node name was remapped or no rules matched, 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_NAMESPACE` if the remapped namespace is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the node name was remapped or no rules matched, 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_NAMESPACE if the remapped namespace is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -260,10 +262,10 @@ rcl_remap_node_namespace( * \param[in] rule The structure to be copied. * Its allocator is used to copy memory into the new structure. * \param[out] rule_out A zero-initialized rcl_remap_t structure to be copied into. - * \return `RCL_RET_OK` if the structure was copied successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the structure was copied successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -283,9 +285,9 @@ rcl_remap_copy( * Lock-Free | Yes * * \param[in] remap The structure to be deallocated. - * \return `RCL_RET_OK` if the memory was successfully freed, or - * \return `RCL_RET_INVALID_ARGUMENT` if any function arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the memory was successfully freed, or + * \return #RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/rmw_implementation_identifier_check.h b/rcl/include/rcl/rmw_implementation_identifier_check.h index 2a1ecd35ac..8836b88742 100644 --- a/rcl/include/rcl/rmw_implementation_identifier_check.h +++ b/rcl/include/rcl/rmw_implementation_identifier_check.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__RMW_IMPLEMENTATION_IDENTIFIER_CHECK_H_ #define RCL__RMW_IMPLEMENTATION_IDENTIFIER_CHECK_H_ @@ -22,9 +24,19 @@ extern "C" #include "rcl/visibility_control.h" +/// The environment variable name to control which RMW implementation is used. #define RMW_IMPLEMENTATION_ENV_VAR_NAME "RMW_IMPLEMENTATION" + +/// The environment variable name to control whether the chosen RMW implementation matches the one that is in use. #define RCL_ASSERT_RMW_ID_MATCHES_ENV_VAR_NAME "RCL_ASSERT_RMW_ID_MATCHES" +/// Check whether the RMW implementation in use matches what the user requested. +/** + * \return #RCL_RET_OK if the RMW implementation in use matches what the user requested, or + * \return #RCL_RET_MISMATCHED_RMW_ID if the RMW implementation does not match, or + * \return #RCL_RET_BAD_ALLOC if memory allocation failed, or + * \return #RCL_RET_ERROR if some other error occurred. + */ RCL_PUBLIC rcl_ret_t rcl_rmw_implementation_identifier_check(void); diff --git a/rcl/include/rcl/security.h b/rcl/include/rcl/security.h index b21bc3f010..b37fd92cf0 100644 --- a/rcl/include/rcl/security.h +++ b/rcl/include/rcl/security.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__SECURITY_H_ #define RCL__SECURITY_H_ @@ -28,18 +30,22 @@ extern "C" #include "rmw/security_options.h" #ifndef ROS_SECURITY_ENCLAVE_OVERRIDE +/// The name of the environment variable containing the security enclave override. # define ROS_SECURITY_ENCLAVE_OVERRIDE "ROS_SECURITY_ENCLAVE_OVERRIDE" #endif #ifndef ROS_SECURITY_KEYSTORE_VAR_NAME +/// The name of the environment variable containing the path to the keystore. # define ROS_SECURITY_KEYSTORE_VAR_NAME "ROS_SECURITY_KEYSTORE" #endif #ifndef ROS_SECURITY_STRATEGY_VAR_NAME +/// The name of the environment variable containing the security strategy. # define ROS_SECURITY_STRATEGY_VAR_NAME "ROS_SECURITY_STRATEGY" #endif #ifndef ROS_SECURITY_ENABLE_VAR_NAME +/// The name of the environment variable controlling whether security is enabled. # define ROS_SECURITY_ENABLE_VAR_NAME "ROS_SECURITY_ENABLE" #endif @@ -47,17 +53,17 @@ extern "C" /** * Initialize the given security options based on the environment. * For more details: - * \sa rcl_security_enabled - * \sa rcl_get_enforcement_policy - * \sa rcl_get_secure_root + * \sa rcl_security_enabled() + * \sa rcl_get_enforcement_policy() + * \sa rcl_get_secure_root() * - * \param[in] name name used to find the securiy root path. + * \param[in] name name used to find the security root path. * \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 + * \return #RCL_RET_OK If the security options are returned properly, or + * \return #RCL_RET_INVALID_ARGUMENT if an argument is not valid, or + * \return #RCL_RET_ERROR if an unexpected error happened */ RCL_PUBLIC rcl_ret_t @@ -68,13 +74,13 @@ rcl_get_security_options_from_environment( /// Check if security has to be used, according to the environment. /** - * If `ROS_SECURITY_ENABLE` environment variable is set to "true", `use_security` will be set to + * If the `ROS_SECURITY_ENABLE` environment variable is set to "true", `use_security` will be set to * true. * * \param[out] use_security Must not be NULL. - * \returns RCL_RET_INVALID_ARGUMENT if an argument is not valid, or - * \returns RCL_RET_ERROR if an unexpected error happened, or - * \returns RCL_RET_OK. + * \return #RCL_RET_INVALID_ARGUMENT if an argument is not valid, or + * \return #RCL_RET_ERROR if an unexpected error happened, or + * \return #RCL_RET_OK. */ RCL_PUBLIC rcl_ret_t @@ -82,14 +88,14 @@ rcl_security_enabled(bool * use_security); /// Get security enforcement policy from the environment. /** - * Sets `policy` based on the value of `ROS_SECURITY_STRATEGY` environment variable. + * Sets `policy` based on the value of the `ROS_SECURITY_STRATEGY` environment variable. * If `ROS_SECURITY_STRATEGY` is "Enforce", `policy` will be `RMW_SECURITY_ENFORCEMENT_ENFORCE`. * If not, `policy` will be `RMW_SECURITY_ENFORCEMENT_PERMISSIVE`. * * \param[out] policy Must not be NULL. - * \returns RCL_RET_INVALID_ARGUMENT if an argument is not valid, or - * \returns RCL_RET_ERROR if an unexpected error happened, or - * \returns RCL_RET_OK. + * \return #RCL_RET_INVALID_ARGUMENT if an argument is not valid, or + * \return #RCL_RET_ERROR if an unexpected error happened, or + * \return #RCL_RET_OK. */ RCL_PUBLIC rcl_ret_t @@ -100,7 +106,7 @@ rcl_get_enforcement_policy(rmw_security_enforcement_policy_t * policy); * Return the security directory associated with the enclave name. * * The value of the environment variable `ROS_SECURITY_KEYSTORE` is used as a root. - * The specific directory to be used, is found from that root using the `name` passed. + * The specific directory to be used is found from that root using the `name` passed. * E.g. for a context named "/a/b/c" and root "/r", the secure root path will be * "/r/a/b/c", where the delimiter "/" is native for target file system (e.g. "\\" for _WIN32). * @@ -113,7 +119,7 @@ rcl_get_enforcement_policy(rmw_security_enforcement_policy_t * policy); * * \param[in] name validated name (a single token) * \param[in] allocator the allocator to use for allocation - * \returns Machine specific (absolute) enclave directory path or NULL on failure. + * \return Machine specific (absolute) enclave directory path or NULL on failure. * Returned pointer must be deallocated by the caller of this function */ RCL_PUBLIC diff --git a/rcl/include/rcl/service.h b/rcl/include/rcl/service.h index a73cb3802b..3b37430438 100644 --- a/rcl/include/rcl/service.h +++ b/rcl/include/rcl/service.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__SERVICE_H_ #define RCL__SERVICE_H_ @@ -50,6 +52,8 @@ typedef struct rcl_service_options_t /** * Should be called to get a null rcl_service_t before passing to * rcl_service_init(). + * + * \return A structure with a zero initialized service. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -138,13 +142,13 @@ rcl_get_zero_initialized_service(void); * \param[in] type_support type support object for the service's type * \param[in] service_name the name of the service * \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 - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \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 + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -176,11 +180,11 @@ rcl_service_init( * * \param[inout] service handle to the service to be deinitialized * \param[in] node a valid (not finalized) handle to the node used to create the service - * \return `RCL_RET_OK` if service was deinitialized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SERVICE_INVALID` if the service is invalid, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if service was deinitialized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SERVICE_INVALID if the service is invalid, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -236,13 +240,13 @@ rcl_service_get_default_options(void); * \param[in] service the handle to the service from which to take * \param[inout] request_header ptr to the struct holding metadata about the request * \param[inout] ros_request type-erased ptr to an allocated ROS request message - * \return `RCL_RET_OK` if the request was taken, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SERVICE_INVALID` if the service is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_SERVICE_TAKE_FAILED` if take failed but no error occurred + * \return #RCL_RET_OK if the request was taken, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SERVICE_INVALID if the service is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SERVICE_TAKE_FAILED if take failed but no error occurred * in the middleware, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -252,7 +256,22 @@ rcl_take_request_with_info( rmw_service_info_t * request_header, void * ros_request); -/// backwards compatibility version that takes a request_id only +/// Backwards compatibility function to ake a pending ROS request using a rcl service. +/** + * This version takes a request ID only. See rcl_take_request_with_info() for a full + * explanation of what this does. + * + * \param[in] service the handle to the service from which to take + * \param[inout] request_header ptr to the struct holding the id of the request + * \param[inout] ros_request type-erased ptr to an allocated ROS request message + * \return #RCL_RET_OK if the request was taken, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SERVICE_INVALID if the service is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SERVICE_TAKE_FAILED if take failed but no error occurred + * in the middleware, or + * \return #RCL_RET_ERROR if an unspecified error occurs. + */ RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t @@ -301,10 +320,10 @@ rcl_take_request( * \param[in] service handle to the service which will make the response * \param[inout] response_header ptr to the struct holding metadata about the request ID * \param[in] ros_response type-erased pointer to the ROS response message - * \return `RCL_RET_OK` if the response was sent successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SERVICE_INVALID` if the service is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the response was sent successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SERVICE_INVALID if the service is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/subscription.h b/rcl/include/rcl/subscription.h index e0d2dce5f3..452cb694bd 100644 --- a/rcl/include/rcl/subscription.h +++ b/rcl/include/rcl/subscription.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__SUBSCRIPTION_H_ #define RCL__SUBSCRIPTION_H_ @@ -141,13 +143,13 @@ rcl_get_zero_initialized_subscription(void); * \param[in] type_support type support object for the topic's type * \param[in] topic_name the name of the topic * \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 - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \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 + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -180,11 +182,11 @@ rcl_subscription_init( * * \param[inout] subscription handle to the subscription to be deinitialized * \param[in] node a valid (not finalized) handle to the node used to create the subscription - * \return `RCL_RET_OK` if subscription was deinitialized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_NODE_INVALID` if the node is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if subscription was deinitialized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_NODE_INVALID if the node is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -198,6 +200,8 @@ rcl_subscription_fini(rcl_subscription_t * subscription, rcl_node_t * node); * - qos = rmw_qos_profile_default * - allocator = rcl_get_default_allocator() * - rmw_subscription_options = rmw_get_default_subscription_options(); + * + * \return A structure containing the default options for a subscription. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -252,13 +256,13 @@ rcl_subscription_get_default_options(void); * \param[inout] ros_message type-erased ptr to a allocated ROS message * \param[out] message_info rmw struct which contains meta-data for the message * \param[in] allocation structure pointer used for memory preallocation (may be NULL) - * \return `RCL_RET_OK` if the message was taken, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_SUBSCRIPTION_TAKE_FAILED` if take failed but no error + * \return #RCL_RET_OK if the message was taken, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error * occurred in the middleware, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -272,7 +276,7 @@ rcl_take( /// Take a sequence of messages from a topic using a rcl subscription. /** - * In contrast to `rcl_take`, this function can take multiple messages at + * In contrast to rcl_take(), this function can take multiple messages at * the same time. * It is the job of the caller to ensure that the type of the message_sequence * argument and the type associated with the subscription, via the type @@ -303,13 +307,13 @@ rcl_take( * \param[inout] message_sequence pointer to a (pre-allocated) message sequence. * \param[inout] message_info_sequence pointer to a (pre-allocated) message info sequence. * \param[in] allocation structure pointer used for memory preallocation (may be NULL) - * \return `RCL_RET_OK` if one or more messages was taken, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_SUBSCRIPTION_TAKE_FAILED` if take failed but no error + * \return #RCL_RET_OK if one or more messages was taken, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error * occurred in the middleware, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -324,7 +328,7 @@ rcl_take_sequence( /// Take a serialized raw message from a topic using a rcl subscription. /** - * In contrast to `rcl_take`, this function stores the taken message in + * In contrast to rcl_take(), this function stores the taken message in * its raw binary representation. * It is the job of the caller to ensure that the type associate with the subscription * matches, and can optionally be deserialized into its ROS message via, the correct @@ -335,7 +339,7 @@ rcl_take_sequence( * Passing a different type to rcl_take produces undefined behavior and cannot * be checked by this function and therefore no deliberate error will occur. * - * Apart from the differences above, this function behaves like `rcl_take`. + * Apart from the differences above, this function behaves like rcl_take(). * *
* Attribute | Adherence @@ -350,13 +354,13 @@ rcl_take_sequence( * \param[inout] serialized_message pointer to a (pre-allocated) serialized message. * \param[out] message_info rmw struct which contains meta-data for the message * \param[in] allocation structure pointer used for memory preallocation (may be NULL) - * \return `RCL_RET_OK` if the message was published, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_SUBSCRIPTION_TAKE_FAILED` if take failed but no error + * \return #RCL_RET_OK if the message was published, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error * occurred in the middleware, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -387,14 +391,14 @@ rcl_take_serialized_message( * \param[inout] loaned_message a pointer to the loaned messages. * \param[out] message_info rmw struct which contains meta-data for the message. * \param[in] allocation structure pointer used for memory preallocation (may be NULL) - * \return `RCL_RET_OK` if the loaned message sequence was taken, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_SUBSCRIPTION_TAKE_FAILED` if take failed but no error + * \return #RCL_RET_OK if the loaned message sequence was taken, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error * occurred in the middleware, or - * \return `RCL_RET_UNIMPLEMENTED` if the middleware does not support that feature, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_UNSUPPORTED if the middleware does not support that feature, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -422,11 +426,11 @@ rcl_take_loaned_message( * * \param[in] subscription the handle to the subscription from which to take * \param[in] loaned_message a pointer to the loaned messages. - * \return `RCL_RET_OK` if the message was published, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_UNIMPLEMENTED` if the middleware does not support that feature, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the message was published, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_UNSUPPORTED if the middleware does not support that feature, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -557,10 +561,10 @@ rcl_subscription_is_valid(const rcl_subscription_t * subscription); * * \param[in] subscription pointer to the rcl subscription * \param[out] publisher_count number of matched publishers - * \return `RCL_RET_OK` if the count was retrieved, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_SUBSCRIPTION_INVALID` if the subscription is invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the count was retrieved, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -599,6 +603,9 @@ rcl_subscription_get_actual_qos(const rcl_subscription_t * subscription); /** * Depending on the middleware and the message type, this will return true if the middleware * can allocate a ROS message instance. + * + * \param[in] subscription The subscription instance to check for the ability to loan messages + * \return `true` if the subscription instance can loan messages, `false` otherwise. */ RCL_PUBLIC bool diff --git a/rcl/include/rcl/time.h b/rcl/include/rcl/time.h index a7bf538649..94089b418e 100644 --- a/rcl/include/rcl/time.h +++ b/rcl/include/rcl/time.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__TIME_H_ #define RCL__TIME_H_ @@ -58,9 +60,13 @@ typedef rcutils_duration_value_t rcl_duration_value_t; */ typedef enum rcl_clock_type_t { + /// Clock uninitialized RCL_CLOCK_UNINITIALIZED = 0, + /// Use ROS time RCL_ROS_TIME, + /// Use system time RCL_SYSTEM_TIME, + /// Use a steady clock time RCL_STEADY_TIME } rcl_clock_type_t; @@ -197,16 +203,16 @@ rcl_clock_valid(rcl_clock_t * clock); * Uses Atomics | No * Lock-Free | Yes * - * [1] If `clock_type` is `RCL_ROS_TIME` + * [1] If `clock_type` is #RCL_ROS_TIME * [2] Function is reentrant, but concurrent calls on the same `clock` object are not safe. * Thread-safety is also affected by that of the `allocator` object. * * \param[in] clock_type the type identifying the time source to provide * \param[in] clock the handle to the clock which is being initialized * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -220,8 +226,8 @@ rcl_clock_init( * This will deallocate all necessary internal structures, and clean up any variables. * It can be combined with any of the init functions. * - * Passing a clock with type RCL_CLOCK_UNINITIALIZED will result in - * RCL_RET_INVALID_ARGUMENT being returned. + * Passing a clock with type #RCL_CLOCK_UNINITIALIZED will result in + * #RCL_RET_INVALID_ARGUMENT being returned. * * This function is not thread-safe with any other function operating on the same * clock object. @@ -239,9 +245,9 @@ rcl_clock_init( * `clock` object. * * \param[in] clock the handle to the clock which is being finalized - * \return `RCL_RET_OK` if the time source was successfully finalized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was successfully finalized, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -249,10 +255,10 @@ rcl_ret_t rcl_clock_fini( rcl_clock_t * clock); -/// Initialize a clock as a RCL_ROS_TIME time source. +/// Initialize a clock as a #RCL_ROS_TIME time source. /** * This will allocate all necessary internal structures, and initialize variables. - * It is specifically setting up a RCL_ROS_TIME time source. + * It is specifically setting up a #RCL_ROS_TIME time source. * *
* Attribute | Adherence @@ -267,10 +273,10 @@ rcl_clock_fini( * * \param[in] clock the handle to the clock which is being initialized * \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. + * \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 RCL_WARN_UNUSED @@ -279,10 +285,10 @@ rcl_ros_clock_init( rcl_clock_t * clock, rcl_allocator_t * allocator); -/// Finalize a clock as a `RCL_ROS_TIME` time source. +/// Finalize a clock as a #RCL_ROS_TIME time source. /** * This will deallocate all necessary internal structures, and clean up any variables. - * It is specifically setting up a `RCL_ROS_TIME` time source. It is expected + * It is specifically setting up a #RCL_ROS_TIME time source. It is expected * to be paired with the init fuction. * * This function is not thread-safe with any other function operating on the same @@ -301,9 +307,9 @@ rcl_ros_clock_init( * `clock` object. * * \param[in] clock the handle to the clock which is being initialized - * \return `RCL_RET_OK` if the time source was successfully finalized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was successfully finalized, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -311,10 +317,10 @@ rcl_ret_t rcl_ros_clock_fini( rcl_clock_t * clock); -/// Initialize a clock as a `RCL_STEADY_TIME` time source. +/// Initialize a clock as a #RCL_STEADY_TIME time source. /** * This will allocate all necessary internal structures, and initialize variables. - * It is specifically setting up a `RCL_STEADY_TIME` time source. + * It is specifically setting up a #RCL_STEADY_TIME time source. * *
* Attribute | Adherence @@ -329,9 +335,9 @@ rcl_ros_clock_fini( * * \param[in] clock the handle to the clock which is being initialized * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -340,9 +346,9 @@ rcl_steady_clock_init( rcl_clock_t * clock, rcl_allocator_t * allocator); -/// Finalize a clock as a `RCL_STEADY_TIME` time source. +/// Finalize a clock as a #RCL_STEADY_TIME time source. /** - * Finalize the clock as a `RCL_STEADY_TIME` time source. + * Finalize the clock as a #RCL_STEADY_TIME time source. * * This will deallocate all necessary internal structures, and clean up any variables. * It is specifically setting up a steady time source. It is expected to be @@ -364,9 +370,9 @@ rcl_steady_clock_init( * `clock` object. * * \param[in] clock the handle to the clock which is being initialized - * \return `RCL_RET_OK` if the time source was successfully finalized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was successfully finalized, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -374,9 +380,9 @@ rcl_ret_t rcl_steady_clock_fini( rcl_clock_t * clock); -/// Initialize a clock as a `RCL_SYSTEM_TIME` time source. +/// Initialize a clock as a #RCL_SYSTEM_TIME time source. /** - * Initialize the clock as a `RCL_SYSTEM_TIME` time source. + * Initialize the clock as a #RCL_SYSTEM_TIME time source. * * This will allocate all necessary internal structures, and initialize variables. * It is specifically setting up a system time source. @@ -395,9 +401,9 @@ rcl_steady_clock_fini( * * \param[in] clock the handle to the clock which is being initialized * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -406,9 +412,9 @@ rcl_system_clock_init( rcl_clock_t * clock, rcl_allocator_t * allocator); -/// Finalize a clock as a `RCL_SYSTEM_TIME` time source. +/// Finalize a clock as a #RCL_SYSTEM_TIME time source. /** - * Finalize the clock as a `RCL_SYSTEM_TIME` time source. + * Finalize the clock as a #RCL_SYSTEM_TIME time source. * * This will deallocate all necessary internal structures, and clean up any variables. * It is specifically setting up a system time source. It is expected to be paired with @@ -429,9 +435,9 @@ rcl_system_clock_init( * `clock` object. * * \param[in] clock the handle to the clock which is being initialized. - * \return `RCL_RET_OK` if the time source was successfully finalized, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was successfully finalized, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -459,9 +465,9 @@ rcl_system_clock_fini( * \param[in] start The time point for the start of the duration. * \param[in] finish The time point for the end of the duration. * \param[out] delta The duration between the start and finish. - * \return `RCL_RET_OK` if the difference was computed successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the difference was computed successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -482,13 +488,13 @@ rcl_difference_times( * Uses Atomics | Yes [1] * Lock-Free | Yes * - * [1] If `clock` is of `RCL_ROS_TIME` type. + * [1] If `clock` is of #RCL_ROS_TIME type. * * \param[in] clock The time source from which to set the value. * \param[out] time_point_value The time_point value to populate. - * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -502,8 +508,8 @@ rcl_clock_get_now(rcl_clock_t * clock, rcl_time_point_value_t * time_point_value * such that the time source will report the set value instead of falling * back to system time. * - * This function is not thread-safe with `rcl_clock_add_jump_callback`, - * nor `rcl_clock_remove_jump_callback` functions when used on the same + * This function is not thread-safe with rcl_clock_add_jump_callback(), + * nor rcl_clock_remove_jump_callback() functions when used on the same * clock object. * *
@@ -518,9 +524,9 @@ rcl_clock_get_now(rcl_clock_t * clock, rcl_time_point_value_t * time_point_value * [2] Function is reentrant, but concurrent calls on the same `clock` object are not safe. * * \param[in] clock The clock to enable. - * \return `RCL_RET_OK` if the time source was enabled successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was enabled successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -529,12 +535,12 @@ rcl_enable_ros_time_override(rcl_clock_t * clock); /// Disable the ROS time abstraction override. /** - * This method will disable the `RCL_ROS_TIME` time abstraction override values, + * This method will disable the #RCL_ROS_TIME time abstraction override values, * such that the time source will report the system time even if a custom * value has been set. * - * This function is not thread-safe with `rcl_clock_add_jump_callback`, - * nor `rcl_clock_remove_jump_callback` functions when used on the same + * This function is not thread-safe with rcl_clock_add_jump_callback(), + * nor rcl_clock_remove_jump_callback() functions when used on the same * clock object. * *
@@ -549,9 +555,9 @@ rcl_enable_ros_time_override(rcl_clock_t * clock); * [2] Function is reentrant, but concurrent calls on the same `clock` object are not safe. * * \param[in] clock The clock to disable. - * \return `RCL_RET_OK` if the time source was disabled successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was disabled successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -559,14 +565,14 @@ rcl_ret_t rcl_disable_ros_time_override(rcl_clock_t * clock); -/// Check if the `RCL_ROS_TIME` time source has the override enabled. +/// Check if the #RCL_ROS_TIME time source has the override enabled. /** * This will populate the is_enabled object to indicate if the * time overide is enabled. If it is enabled, the set value will be returned. * Otherwise this time source will return the equivalent to system time abstraction. * - * This function is not thread-safe with `rcl_enable_ros_time_override` nor - * `rcl_disable_ros_time_override` functions when used on the same clock object. + * This function is not thread-safe with rcl_enable_ros_time_override() nor + * rcl_disable_ros_time_override() functions when used on the same clock object. * *
* Attribute | Adherence @@ -580,9 +586,9 @@ rcl_disable_ros_time_override(rcl_clock_t * clock); * * \param[in] clock The clock to query. * \param[out] is_enabled Whether the override is enabled.. - * \return `RCL_RET_OK` if the time source was queried successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was queried successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -590,15 +596,15 @@ rcl_ret_t rcl_is_enabled_ros_time_override( rcl_clock_t * clock, bool * is_enabled); -/// Set the current time for this `RCL_ROS_TIME` time source. +/// Set the current time for this #RCL_ROS_TIME time source. /** - * This function will update the internal storage for the `RCL_ROS_TIME` + * This function will update the internal storage for the #RCL_ROS_TIME * time source. * If queried and override enabled the time source will return this value, * otherwise it will return the system time. * - * This function is not thread-safe with `rcl_clock_add_jump_callback`, - * nor `rcl_clock_remove_jump_callback` functions when used on the same + * This function is not thread-safe with rcl_clock_add_jump_callback(), + * nor rcl_clock_remove_jump_callback() functions when used on the same * clock object. * *
@@ -614,9 +620,9 @@ rcl_is_enabled_ros_time_override( * * \param[in] clock The clock to update. * \param[in] time_value The new current time. - * \return `RCL_RET_OK` if the time source was set successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the time source was set successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -631,9 +637,9 @@ rcl_set_ros_time_override( * The user_data pointer is passed to the callback as the last argument. * A callback and user_data pair must be unique among the callbacks added to a clock. * - * This function is not thread-safe with `rcl_clock_remove_jump_callback`, - * `rcl_enable_ros_time_override`, `rcl_disable_ros_time_override` nor - * `rcl_set_ros_time_override` functions when used on the same clock object. + * This function is not thread-safe with rcl_clock_remove_jump_callback(), + * rcl_enable_ros_time_override(), rcl_disable_ros_time_override() nor + * rcl_set_ros_time_override() functions when used on the same clock object. * *
* Attribute | Adherence @@ -651,10 +657,10 @@ rcl_set_ros_time_override( * \param[in] threshold Criteria indicating when to call the callback. * \param[in] callback A 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 - * \return `RCL_RET_BAD_ALLOC` if a memory allocation failed, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` an unspecified error occurs. + * \return #RCL_RET_OK if the callback was added successfully, or + * \return #RCL_RET_BAD_ALLOC if a memory allocation failed, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -665,9 +671,9 @@ rcl_clock_add_jump_callback( /// Remove a previously added time jump callback. /** - * This function is not thread-safe with `rcl_clock_add_jump_callback` - * `rcl_enable_ros_time_override`, `rcl_disable_ros_time_override` nor - * `rcl_set_ros_time_override` functions when used on the same clock object. + * This function is not thread-safe with rcl_clock_add_jump_callback() + * rcl_enable_ros_time_override(), rcl_disable_ros_time_override() nor + * rcl_set_ros_time_override() functions when used on the same clock object. * *
* Attribute | Adherence @@ -684,10 +690,10 @@ rcl_clock_add_jump_callback( * \param[in] clock The clock to remove a jump callback from. * \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 - * \return `RCL_RET_BAD_ALLOC` if a memory allocation failed, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` the callback was not found or an unspecified error occurs. + * \return #RCL_RET_OK if the callback was added successfully, or + * \return #RCL_RET_BAD_ALLOC if a memory allocation failed, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR the callback was not found or an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED diff --git a/rcl/include/rcl/timer.h b/rcl/include/rcl/timer.h index ecc35f0739..b1a213433d 100644 --- a/rcl/include/rcl/timer.h +++ b/rcl/include/rcl/timer.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__TIMER_H_ #define RCL__TIMER_H_ @@ -141,11 +143,11 @@ rcl_get_zero_initialized_timer(void); * \param[in] period the duration between calls to the callback in nanoseconds * \param[in] callback the user defined function to be called every period * \param[in] allocator the allocator to use for allocations - * \return `RCL_RET_OK` if the timer was initialized successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ALREADY_INIT` if the timer was already initialized, or - * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the timer was initialized successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ALREADY_INIT if the timer was already initialized, or + * \return #RCL_RET_BAD_ALLOC if allocating memory failed, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -181,8 +183,8 @@ rcl_timer_init( * [3] if `atomic_is_lock_free()` returns true for `atomic_bool` * * \param[inout] timer the handle to the timer to be finalized. - * \return `RCL_RET_OK` if the timer was finalized successfully, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the timer was finalized successfully, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -222,11 +224,11 @@ rcl_timer_fini(rcl_timer_t * timer); * [2] if `atomic_is_lock_free()` returns true for `atomic_int_least64_t` * * \param[inout] timer the handle to the timer to call - * \return `RCL_RET_OK` if the timer was called 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_TIMER_CANCELED` if the timer has been canceled, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK if the timer was called 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_TIMER_CANCELED if the timer has been canceled, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -249,10 +251,10 @@ rcl_timer_call(rcl_timer_t * timer); * * \param[in] timer the handle to the timer which is being queried * \param[out] clock the rcl_clock_t * in which the clock 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. + * \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 RCL_WARN_UNUSED @@ -279,10 +281,10 @@ rcl_timer_clock(rcl_timer_t * timer, rcl_clock_t ** clock); * * \param[in] timer the handle to the timer which is being checked * \param[out] is_ready the bool used to store the result of the calculation - * \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. + * \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_WARN_UNUSED @@ -314,10 +316,10 @@ rcl_timer_is_ready(const rcl_timer_t * timer, bool * is_ready); * * \param[in] timer the handle to the timer that is being queried * \param[out] time_until_next_call the output variable for the result - * \return `RCL_RET_OK` if the timer until next call was successfully calculated, 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. + * \return #RCL_RET_OK if the timer until next call was successfully calculated, 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_WARN_UNUSED @@ -346,10 +348,10 @@ rcl_timer_get_time_until_next_call(const rcl_timer_t * timer, int64_t * time_unt * * \param[in] timer the handle to the timer which is being queried * \param[out] time_since_last_call the struct in which the time is stored - * \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. + * \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_WARN_UNUSED @@ -373,9 +375,9 @@ rcl_timer_get_time_since_last_call(const rcl_timer_t * timer, int64_t * time_sin * * \param[in] timer the handle to the timer which is being queried * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -403,9 +405,9 @@ rcl_timer_get_period(const rcl_timer_t * timer, int64_t * period); * \param[in] timer the handle to the timer which is being modified * \param[out] new_period the int64_t to exchange into the timer * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -480,10 +482,10 @@ rcl_timer_exchange_callback(rcl_timer_t * timer, const rcl_timer_callback_t new_ * [1] if `atomic_is_lock_free()` returns true for `atomic_int_least64_t` * * \param[inout] timer the timer to be canceled - * \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. + * \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_WARN_UNUSED @@ -509,9 +511,9 @@ rcl_timer_cancel(rcl_timer_t * timer); * * \param[in] timer the timer to be queried * \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_ERROR` an unspecified error occur. + * \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_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -534,10 +536,10 @@ rcl_timer_is_canceled(const rcl_timer_t * timer, bool * is_canceled); * [1] if `atomic_is_lock_free()` returns true for `atomic_int_least64_t` * * \param[inout] timer the timer to be reset - * \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. + * \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_WARN_UNUSED diff --git a/rcl/include/rcl/types.h b/rcl/include/rcl/types.h index bca7bbe7e6..15ef8b5ae6 100644 --- a/rcl/include/rcl/types.h +++ b/rcl/include/rcl/types.h @@ -12,12 +12,16 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__TYPES_H_ #define RCL__TYPES_H_ #include +/// The type that holds an rcl return code. typedef rmw_ret_t rcl_ret_t; + /// Success return code. #define RCL_RET_OK RMW_RET_OK /// Unspecified error return code. @@ -50,7 +54,9 @@ typedef rmw_ret_t rcl_ret_t; // rcl node specific ret codes in 2XX /// Invalid rcl_node_t given return code. #define RCL_RET_NODE_INVALID 200 +/// Invalid node name return code. #define RCL_RET_NODE_INVALID_NAME 201 +/// Invalid node namespace return code. #define RCL_RET_NODE_INVALID_NAMESPACE 202 /// Failed to find node name #define RCL_RET_NODE_NAME_NON_EXISTENT 203 diff --git a/rcl/include/rcl/validate_enclave_name.h b/rcl/include/rcl/validate_enclave_name.h index 7daee9bd7d..6fc61ecbef 100644 --- a/rcl/include/rcl/validate_enclave_name.h +++ b/rcl/include/rcl/validate_enclave_name.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__VALIDATE_ENCLAVE_NAME_H_ #define RCL__VALIDATE_ENCLAVE_NAME_H_ @@ -27,32 +29,48 @@ extern "C" #include "rcl/types.h" #include "rcl/visibility_control.h" +/// The enclave name is valid. #define RCL_ENCLAVE_NAME_VALID RMW_NAMESPACE_VALID + +/// The enclave name is invalid because it is an empty string. #define RCL_ENCLAVE_NAME_INVALID_IS_EMPTY_STRING RMW_NAMESPACE_INVALID_IS_EMPTY_STRING + +/// The enclave name is invalid because it is not absolute. #define RCL_ENCLAVE_NAME_INVALID_NOT_ABSOLUTE RMW_NAMESPACE_INVALID_NOT_ABSOLUTE + +/// The enclave name is invalid because it ends with a forward slash. #define RCL_ENCLAVE_NAME_INVALID_ENDS_WITH_FORWARD_SLASH \ RMW_NAMESPACE_INVALID_ENDS_WITH_FORWARD_SLASH -#define RCL_ENCLAVE_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS \ + +/// The enclave name is invalid because it has characters that are not allowed. +#define RCL_ENCLAVE_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS \ RMW_NAMESPACE_INVALID_CONTAINS_UNALLOWED_CHARACTERS + +/// The enclave name is invalid because it contains repeated forward slashes. #define RCL_ENCLAVE_NAME_INVALID_CONTAINS_REPEATED_FORWARD_SLASH \ RMW_NAMESPACE_INVALID_CONTAINS_REPEATED_FORWARD_SLASH + +/// The enclave name is invalid because one of the tokens starts with a number. #define RCL_ENCLAVE_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER \ RMW_NAMESPACE_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER + +/// The enclave name is invalid because the name is too long. #define RCL_ENCLAVE_NAME_INVALID_TOO_LONG RMW_NAMESPACE_INVALID_TOO_LONG +/// The maximum length of an enclave name. #define RCL_ENCLAVE_NAME_MAX_LENGTH RMW_NODE_NAME_MAX_NAME_LENGTH /// Determine if a given enclave name is valid. /** - * The same rules as \ref rmw_validate_namespace are used. + * The same rules as rmw_validate_namespace() are used. * The only difference is in the maximum allowed length, which can be up to 255 characters. * * \param[in] enclave enclave to be validated * \param[out] validation_result int in which the result of the check is stored * \param[out] invalid_index index of the input string where an error occurred - * \returns `RMW_RET_OK` on successfully running the check, or - * \returns `RMW_RET_INVALID_ARGUMENT` on invalid parameters, or - * \returns `RMW_RET_ERROR` when an unspecified error occurs. + * \return #RCL_RET_OK on successfully running the check, or + * \return #RCL_RET_INVALID_ARGUMENT on invalid parameters, or + * \return #RCL_RET_ERROR when an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -64,10 +82,16 @@ rcl_validate_enclave_name( /// Deterimine if a given enclave name is valid. /** - * This is an overload of \ref rcl_validate_enclave_name with an extra parameter + * This is an overload of rcl_validate_enclave_name() with an extra parameter * for the length of enclave. * - * \param[in] enclave_length The number of characters in enclave. + * \param[in] enclave enclave to be validated + * \param[in] enclave_length The number of characters in enclave + * \param[out] validation_result int in which the result of the check is stored + * \param[out] invalid_index index of the input string where an error occurred + * \return #RCL_RET_OK on successfully running the check, or + * \return #RCL_RET_INVALID_ARGUMENT on invalid parameters, or + * \return #RCL_RET_ERROR when an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -79,6 +103,11 @@ rcl_validate_enclave_name_with_size( size_t * invalid_index); /// Return a validation result description, or NULL if unknown or RCL_ENCLAVE_NAME_VALID. +/** + * \param[in] validation_result The validation result to get the string for + * \return A string description of the validation result if successful, or + * \return NULL if the validation result is invalid. + */ RCL_PUBLIC RCL_WARN_UNUSED const char * diff --git a/rcl/include/rcl/validate_topic_name.h b/rcl/include/rcl/validate_topic_name.h index ed884ac1f7..76696f2127 100644 --- a/rcl/include/rcl/validate_topic_name.h +++ b/rcl/include/rcl/validate_topic_name.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__VALIDATE_TOPIC_NAME_H_ #define RCL__VALIDATE_TOPIC_NAME_H_ @@ -24,15 +26,34 @@ extern "C" #include "rcl/types.h" #include "rcl/visibility_control.h" +/// The topic name is valid. #define RCL_TOPIC_NAME_VALID 0 + +/// The topic name is invalid because it is an empty string. #define RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING 1 + +/// The topic name is invalid because it ends with a forward slash. #define RCL_TOPIC_NAME_INVALID_ENDS_WITH_FORWARD_SLASH 2 + +/// The topic name is invalid because it has characters that are not allowed. #define RCL_TOPIC_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS 3 + +/// The topic name is invalid because one of the tokens starts with a number. #define RCL_TOPIC_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER 4 + +/// The topic name is invalid because it has an unmatched curly brace. #define RCL_TOPIC_NAME_INVALID_UNMATCHED_CURLY_BRACE 5 + +/// The topic name is invalid because it has a misplaced tilde in it. #define RCL_TOPIC_NAME_INVALID_MISPLACED_TILDE 6 + +/// The topic name is invalid because a tilde is not directly followed by a forward slash. #define RCL_TOPIC_NAME_INVALID_TILDE_NOT_FOLLOWED_BY_FORWARD_SLASH 7 + +/// The topic name is invalid because one of the substitutions has characters that are not allowed. #define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_CONTAINS_UNALLOWED_CHARACTERS 8 + +/// The topic name is invalid because one of the substitutions starts with a number. #define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_STARTS_WITH_NUMBER 9 /// Validate a given topic name. @@ -82,9 +103,9 @@ extern "C" * \param[in] topic_name the topic name to be validated, must be null terminated * \param[out] validation_result the reason for validation failure, if any * \param[out] invalid_index index of violation if the input topic is invalid - * \return `RCL_RET_OK` if the topic name was expanded successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if the topic name was expanded successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -101,8 +122,11 @@ rcl_validate_topic_name( * \param[in] topic_name_length The number of characters in topic_name. * \param[out] validation_result the reason for validation failure, if any * \param[out] invalid_index index of violation if the input topic is invalid + * \return #RCL_RET_OK if the topic name was expanded successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_ERROR if an unspecified error occurs. * - * \sa rcl_validate_topic_name(const char *, int *, size_t *) + * \sa rcl_validate_topic_name() */ RCL_PUBLIC RCL_WARN_UNUSED @@ -114,6 +138,11 @@ rcl_validate_topic_name_with_size( size_t * invalid_index); /// Return a validation result description, or NULL if unknown or RCL_TOPIC_NAME_VALID. +/** + * \param[in] validation_result The validation result to get the string for + * \return A string description of the validation result if successful, or + * \return NULL if the validation result is invalid. + */ RCL_PUBLIC RCL_WARN_UNUSED const char * diff --git a/rcl/include/rcl/wait.h b/rcl/include/rcl/wait.h index f900d11075..229c48f8eb 100644 --- a/rcl/include/rcl/wait.h +++ b/rcl/include/rcl/wait.h @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +/// @file + #ifndef RCL__WAIT_H_ #define RCL__WAIT_H_ @@ -118,13 +120,13 @@ rcl_get_zero_initialized_wait_set(void); * \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. + * \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 RCL_WARN_UNUSED @@ -161,10 +163,10 @@ rcl_wait_set_init( * Lock-Free | Yes * * \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. + * \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 RCL_WARN_UNUSED @@ -186,10 +188,10 @@ rcl_wait_set_fini(rcl_wait_set_t * wait_set); * * \param[in] wait_set the handle to the 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. + * \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 RCL_WARN_UNUSED @@ -216,11 +218,11 @@ rcl_wait_set_get_allocator(const rcl_wait_set_t * wait_set, rcl_allocator_t * al * \param[in] subscription the subscription to be added to the wait set * \param[out] index the index of the added subscription in the storage container. * This parameter is optional and can be set to `NULL` to be ignored. - * \return `RCL_RET_OK` if added successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is zero initialized, or - * \return `RCL_RET_WAIT_SET_FULL` if the subscription set is full, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if added successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_WAIT_SET_INVALID if the wait set is zero initialized, or + * \return #RCL_RET_WAIT_SET_FULL if the subscription set is full, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -248,10 +250,10 @@ rcl_wait_set_add_subscription( * Lock-Free | Yes * * \param[inout] wait_set struct to have its entities cleared - * \return `RCL_RET_OK` if cleared successfully, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is zero initialized, or - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \return #RCL_RET_OK if cleared successfully, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_WAIT_SET_INVALID if the wait set is zero initialized, or + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -291,10 +293,10 @@ rcl_wait_set_clear(rcl_wait_set_t * wait_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 - * \return `RCL_RET_ERROR` if an unspecified error occurs. + * \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 + * \return #RCL_RET_ERROR if an unspecified error occurs. */ RCL_PUBLIC RCL_WARN_UNUSED @@ -458,12 +460,12 @@ rcl_wait_set_add_event( * * \param[inout] wait_set the set of things to be waited on and to be pruned if not ready * \param[in] timeout the duration to wait for the wait set to be ready, in nanoseconds - * \return `RCL_RET_OK` something in the wait set became ready, or - * \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or - * \return `RCL_RET_WAIT_SET_INVALID` if the wait set is zero initialized, or - * \return `RCL_RET_WAIT_SET_EMPTY` if the wait set contains no items, or - * \return `RCL_RET_TIMEOUT` if the timeout expired before something was ready, or - * \return `RCL_RET_ERROR` an unspecified error occur. + * \return #RCL_RET_OK something in the wait set became ready, or + * \return #RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or + * \return #RCL_RET_WAIT_SET_INVALID if the wait set is zero initialized, or + * \return #RCL_RET_WAIT_SET_EMPTY if the wait set contains no items, or + * \return #RCL_RET_TIMEOUT if the timeout expired before something was ready, or + * \return #RCL_RET_ERROR an unspecified error occur. */ RCL_PUBLIC RCL_WARN_UNUSED