Skip to content
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

Cleanup documentation for doxygen. #896

Merged
merged 2 commits into from
Mar 9, 2021
Merged

Cleanup documentation for doxygen. #896

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bdbc054
Cleanup documentation for doxygen.
clalancette Mar 8, 2021
2206ac8
Fixes from review.
clalancette Mar 9, 2021
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
22 changes: 22 additions & 0 deletions rcl/include/rcl/allocator.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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_

Expand All @@ -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.
clalancette marked this conversation as resolved.
Show resolved Hide resolved
/**
* \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)

Expand Down
103 changes: 67 additions & 36 deletions rcl/include/rcl/arguments.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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_

Expand All @@ -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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
42 changes: 22 additions & 20 deletions rcl/include/rcl/client.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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_

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading