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 <clalancette@openrobotics.org>

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)
 

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

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