From bdbc054a4a3e41ff3a8c2017f3bd0e072316f7bf Mon Sep 17 00:00:00 2001 From: Chris Lalancette Date: Mon, 8 Mar 2021 14:00:23 +0000 Subject: [PATCH 1/2] Cleanup documentation for doxygen. In particular: 1. Add in @file on all of the files we want indexed (otherwise Doxygen just ignores them). 2. Make sure to document all things that are missing (as pointed out by Doxygen). 3. Switch to #ENUM to reference enums (this makes Doxygen put links in properly). 4. Switch from `my_func` or `my_func()` to my_func() everywhere (Doxygen supports all 3 for making links, but for consistency we just stick with one style). 5. Hide a few things from Doxygen. 6. Switch all \returns to \return (Doxygen supports both, but we should be consistent). Signed-off-by: Chris Lalancette --- rcl/include/rcl/allocator.h | 22 +++ rcl/include/rcl/arguments.h | 103 ++++++---- rcl/include/rcl/client.h | 42 +++-- rcl/include/rcl/context.h | 65 ++++--- rcl/include/rcl/domain_id.h | 9 +- rcl/include/rcl/event.h | 42 +++-- rcl/include/rcl/expand_topic_name.h | 26 +-- rcl/include/rcl/graph.h | 166 +++++++++-------- rcl/include/rcl/guard_condition.h | 38 ++-- rcl/include/rcl/init.h | 42 +++-- rcl/include/rcl/init_options.h | 44 ++--- rcl/include/rcl/lexer.h | 10 +- rcl/include/rcl/lexer_lookahead.h | 42 +++-- rcl/include/rcl/localhost.h | 8 +- rcl/include/rcl/log_level.h | 50 ++--- rcl/include/rcl/logging.h | 44 +++-- rcl/include/rcl/logging_rosout.h | 30 +-- rcl/include/rcl/node.h | 60 +++--- rcl/include/rcl/node_options.h | 20 +- rcl/include/rcl/publisher.h | 99 +++++----- rcl/include/rcl/remap.h | 60 +++--- .../rcl/rmw_implementation_identifier_check.h | 13 ++ rcl/include/rcl/security.h | 40 ++-- rcl/include/rcl/service.h | 65 ++++--- rcl/include/rcl/subscription.h | 105 ++++++----- rcl/include/rcl/time.h | 176 +++++++++--------- rcl/include/rcl/timer.h | 92 ++++----- rcl/include/rcl/types.h | 6 + rcl/include/rcl/validate_enclave_name.h | 41 +++- rcl/include/rcl/validate_topic_name.h | 37 +++- rcl/include/rcl/wait.h | 70 +++---- 31 files changed, 955 insertions(+), 712 deletions(-) diff --git a/rcl/include/rcl/allocator.h b/rcl/include/rcl/allocator.h index 1b3906f1e..ab26fcf1f 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 bd2c25d96..2dbfa993b 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,49 @@ 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 +140,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 +195,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 +247,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 +296,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 +326,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 +360,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 +390,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 +414,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 +437,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 97dade4f2..e4285a031 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 9275364db..b5604ddcc 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 5cb696aec..946c6830d 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 6798a9d5e..a366dd45b 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 4816cbfbe..058e57e23 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 e4756937d..9392573e1 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 9f40ccd6c..a6727d3a2 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 42b07b5f0..a85aae609 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 1b97b82ac..a72bf1333 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 032bf8c88..7d652def5 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 d50166e3f..79fe9b958 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 551b36702..2c5123a59 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 14a8ead5d..a907ad8ba 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 1014853d5..7b70b6977 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 087e981cf..5bbac1bdf 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 011347fd3..c21378aa0 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 acb3f1a74..0da2b0641 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 3c274d95a..85e26bfd5 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 82f0b0e04..4de969cf2 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 2a1ecd35a..cf39fc077 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,20 @@ 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 b21bc3f01..b37fd92cf 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 a73cb3802..3b3743043 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 e0d2dce5f..452cb694b 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 a7bf53864..94089b418 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 ecc35f073..b1a213433 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 bca7bbe7e..15ef8b5ae 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 7daee9bd7..d6c44de5a 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 + +/// 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 ed884ac1f..76696f212 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 f900d1107..229c48f8e 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 From 2206ac80001ea69ecadf02c49234d048a8051294 Mon Sep 17 00:00:00 2001 From: Chris Lalancette Date: Tue, 9 Mar 2021 21:58:56 +0000 Subject: [PATCH 2/2] Fixes from review. Signed-off-by: Chris Lalancette --- rcl/include/rcl/allocator.h | 2 +- rcl/include/rcl/remap.h | 2 +- rcl/include/rcl/service.h | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/rcl/include/rcl/allocator.h b/rcl/include/rcl/allocator.h index ab26fcf1f..c57ec0fc3 100644 --- a/rcl/include/rcl/allocator.h +++ b/rcl/include/rcl/allocator.h @@ -30,7 +30,7 @@ extern "C" */ typedef rcutils_allocator_t rcl_allocator_t; -/// Return a properly initialized rcutils_allocator_t with default values. +/// Return a properly initialized rcl_allocator_t with default values. /** * \sa rcutils_get_default_allocator() */ diff --git a/rcl/include/rcl/remap.h b/rcl/include/rcl/remap.h index 4de969cf2..fcf0baa53 100644 --- a/rcl/include/rcl/remap.h +++ b/rcl/include/rcl/remap.h @@ -60,7 +60,7 @@ rcl_get_zero_initialized_remap(void); * \sa rcl_get_global_arguments() * * Remap rules are checked in the order they were given. - * For rules passed to rcl_ini()` this usually is the order they were passed on the command line. + * For rules passed to rcl_init() 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. diff --git a/rcl/include/rcl/service.h b/rcl/include/rcl/service.h index 3b3743043..87e182ad5 100644 --- a/rcl/include/rcl/service.h +++ b/rcl/include/rcl/service.h @@ -256,7 +256,7 @@ rcl_take_request_with_info( rmw_service_info_t * request_header, void * ros_request); -/// Backwards compatibility function to ake a pending ROS request using a rcl service. +/// Backwards compatibility function to take 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.