diff --git a/rmw/include/rmw/init_options.h b/rmw/include/rmw/init_options.h index 45ad24b8..1fe69ba7 100644 --- a/rmw/include/rmw/init_options.h +++ b/rmw/include/rmw/init_options.h @@ -71,7 +71,7 @@ RMW_WARN_UNUSED rmw_init_options_t rmw_get_zero_initialized_init_options(void); -/// Initialize given init_options with the default values and implementation specific values. +/// Initialize given init options with the default values and implementation specific values. /** * The given allocator is used, if required, during setup of the init options, * but is also used during initialization. @@ -80,6 +80,13 @@ rmw_get_zero_initialized_init_options(void); * * The `impl` pointer should not be changed manually. * + * \pre The given init options must be zero initialized. + * + * \post If initialization fails, init options will remain zero initialized. + * + * \remark Giving an already initialized init options will result + * in a failure with return code `RMW_RET_INVALID_ARGUMENT`. + * *
* Attribute | Adherence * ------------------ | ------------- @@ -93,7 +100,6 @@ rmw_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 `RMW_RET_OK` if setup is successful, or - * \return `RMW_RET_INVALID_ARGUMENT` if init_options has already be initialized, or * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or * \return `RMW_RET_ERROR` if an unspecified error occurs. @@ -108,11 +114,16 @@ rmw_init_options_init(rmw_init_options_t * init_options, rcutils_allocator_t all * The allocator from the source is used for any allocations and stored in the * destination. * - * The destination should either be zero initialized with - * `rmw_get_zero_initialized_init_options()` or should have had - * `rmw_init_options_fini()` called on it. - * Giving an already initialized init options for the destination will result - * in a failure with return code `RMW_RET_INVALID_ARGUMENT`. + * \pre The source init options must have been initialized + * i.e. had `rmw_init_options_init()` called on. + * \pre The destination init options must be zero initialized. + * + * \post If copy fails, destination init options will remain zero initialized. + * + * \remark Giving an zero initialized init options as a source will result + * in a failure with return code `RMW_RET_INVALID_ARGUMENT`. + * \remark Giving an already initialized init options for the destination will result + * in a failure with return code `RMW_RET_INVALID_ARGUMENT`. * *
* Attribute | Adherence @@ -129,7 +140,6 @@ rmw_init_options_init(rmw_init_options_t * init_options, rcutils_allocator_t all * \return `RMW_RET_OK` if the copy is successful, or * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation * identifier for src does not match the implementation of this function, or - * \return `RMW_RET_INVALID_ARGUMENT` if the dst has already be initialized, or * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or * \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or * \return `RMW_RET_ERROR` if an unspecified error occurs. @@ -139,10 +149,19 @@ RMW_WARN_UNUSED rmw_ret_t rmw_init_options_copy(const rmw_init_options_t * src, rmw_init_options_t * dst); -/// Finalize the given init_options. +/// Finalize the given init options. /** - * The given init_options must be non-`NULL` and valid, i.e. had - * `rmw_init_options_init()` called on it but not this function yet. + * This function will return early if a logical error, such as `RMW_RET_INVALID_ARGUMENT` + * or `RMW_RET_INCORRECT_RMW_IMPLEMENTATION`, ensues, leaving the given init options + * unchanged. + * Otherwise, it will proceed despite errors, freeing as much resources as it can and zero + * initializing the given init options. + * + * \pre The given init options must have been initialized + * i.e. had `rmw_init_options_init()` called on. + * + * \remarks If init options are zero initialized, + * then `RMW_RET_INVALID_ARGUMENT` is returned. * *
* Attribute | Adherence @@ -154,9 +173,11 @@ rmw_init_options_copy(const rmw_init_options_t * src, rmw_init_options_t * dst); * * This should be defined by the rmw implementation. * - * \param[inout] init_options object to be setup - * \return `RMW_RET_OK` if setup is successful, or + * \param[inout] init_options object to finalized + * \return `RMW_RET_OK` if finalization is successful, or * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation + * identifier does not match the implementation of this function, or * \return `RMW_RET_ERROR` if an unspecified error occurs. */ RMW_PUBLIC