Skip to content

Update init options API documentation. #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 24, 2020
Merged

Update init options API documentation. #244

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1214f73
Update init options API documentations.
hidmic Jun 23, 2020
cecc75b
Add a few more pre-conditions.
hidmic Jun 23, 2020
f5c05f9
Clarify rmw_init_options_fini() API contract.
hidmic Jun 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions rmw/include/rmw/init_options.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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`.
*
* <hr>
* Attribute | Adherence
* ------------------ | -------------
Expand All @@ -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.
Expand All @@ -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`.
*
* <hr>
* Attribute | Adherence
Expand All @@ -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.
Expand All @@ -139,10 +149,16 @@ 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.
* \pre The given init options must have been initialized
* i.e. had `rmw_init_options_init()` called on.
*
* \post Finalized init options are zero initialized
* i.e. it can be initialized again.
*
* \remarks If init options are zero initialized,
* then `RMW_RET_INVALID_ARGUMENT` is returned.
*
* <hr>
* Attribute | Adherence
Expand All @@ -154,9 +170,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
Expand Down