Improved documentation

README.md

@@ -31,6 +31,8 @@ The API is a combination of parts:
     - RCUTILS_LOG_ERROR_SKIPFIRST_NAMED()
   - rcutils/logging_macros.h
   - rcutils/logging.h
+- Some basic utilities to load, unload and get symbols from shared libraries at run-time.
+  - rcutils/shared_library.h
 - A string replacement function which takes an allocator, based on http://creativeandcritical.net/str-replace-c:
   - rcutils_repl_str()
   - rcutils/repl_str.h

include/rcutils/allocator.h

@@ -109,6 +109,8 @@ rcutils_get_default_allocator(void);
 /// Return true if the given allocator has non-null function pointers.
 /**
  * Will also return false if the allocator pointer is null.
+ *
+ * \param[in] allocator allocator to be checked by the function
  */
 RCUTILS_PUBLIC
 RCUTILS_WARN_UNUSED
@@ -130,6 +132,9 @@ rcutils_allocator_is_valid(const rcutils_allocator_t * allocator);
 /**
  * This function will return `NULL` if the allocator is `NULL` or has `NULL` for
  * function pointer fields.
+ * \param[inout] pointer to the memory which will be reallocate
+ * \param[in] size in bytes
+ * \param[in] allocator to be used to allocate and deallocate memory
  */
 RCUTILS_PUBLIC
 RCUTILS_WARN_UNUSED

include/rcutils/cmdline_parser.h

@@ -24,10 +24,25 @@ extern "C"
 
 #include "rcutils/visibility_control.h"
 
+/// Return if true if the option is defined in the command line arguments or false otherwise.
+/**
+* \param[in] begin first element to check in the array
+* \param[in] end last element to check in the array
+* \param[in] option string to find in the array of arguments
+* \return if the option exists returns true, otherwise returns false.
+ */
 RCUTILS_PUBLIC
 bool
 rcutils_cli_option_exist(char ** begin, char ** end, const char * option);
 
+/// Return the value for a specific option of the command line arguments.
+/**
+* \param[in] begin first element to check in the array
+* \param[in] end last element to check in the array
+* \param[in] option string to find in the array of arguments
+* \return the value for a specific option of the command line arguments or `NULL` if the option
+* doesn't exist
+ */
 RCUTILS_PUBLIC
 char *
 rcutils_cli_get_option(char ** begin, char ** end, const char * option);

include/rcutils/error_handling.h

@@ -130,6 +130,7 @@ static_assert(
  * If already initialized, the given allocator is ignored, even if it does not
  * match the allocator used originally to initialize the thread-local storage.
  *
+ * \param[in] allocator to be used to allocate and deallocate memory
  * \return `RCUTILS_RET_OK` if successful, or
  * \return `RCUTILS_RET_INVALID_ARGUMENT` if the allocator is invalid, or
  * \return `RCUTILS_RET_BAD_ALLOC` if allocating memory fails, or

include/rcutils/filesystem.h

@@ -31,9 +31,9 @@ extern "C"
 /**
  * \param[in] buffer Allocated string to store current directory path to
  * \param[in] max_length maximum length to be stored in buffer
- * \return bool True if success
- *              False if buffer is NULL
- *              False on failure
+ * \return `True` if success
+ * \return `False` if buffer is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 RCUTILS_WARN_UNUSED
@@ -43,9 +43,9 @@ rcutils_get_cwd(char * buffer, size_t max_length);
 /// Check if the provided path points to a directory.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if directory
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if directory
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -54,9 +54,9 @@ rcutils_is_directory(const char * abs_path);
 /// Check if the provided path points to a file.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if file
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if file
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -65,9 +65,9 @@ rcutils_is_file(const char * abs_path);
 /// Check if the provided path points to an existing file/folder.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if the path exists
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if the path exists
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -76,9 +76,9 @@ rcutils_exists(const char * abs_path);
 /// Check if the provided path points to a file/folder readable by current user.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if the file is readable
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if the file is readable
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -87,9 +87,9 @@ rcutils_is_readable(const char * abs_path);
 /// Check if the provided path points to a file/folder writable by current user.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if the file is writable
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if the file is writable
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -98,9 +98,9 @@ rcutils_is_writable(const char * abs_path);
 /// Check if the provided path points to a file/folder both readable and writable by current user.
 /**
  * \param[in] abs_path Absolute path to check.
- * \return bool True if the file is redable and writable False otherwise
- *              False if abs_path is NULL
- *              False on failure
+ * \return `True` if the file is redable and writable False otherwise
+ * \return `False` if abs_path is NULL
+ * \return `False` on failure
  */
 RCUTILS_PUBLIC
 bool
@@ -115,9 +115,9 @@ rcutils_is_readable_and_writable(const char * abs_path);
  * \param[in] left_hand_path
  * \param[in] right_hand_path
  * \param[in] allocator
- * \return char * concatenated path on success
- *         NULL on invalid arguments
- *         NULL on failure
+ * \return concatenated path on success
+ * \return `NULL` on invalid arguments
+ * \return `NULL` on failure
  */
 RCUTILS_PUBLIC
 char *
@@ -134,9 +134,9 @@ rcutils_join_path(
  *
  * \param[in] path
  * \param[in] allocator
- * \return char * path using platform specific delimiters on success
- *         NULL on invalid arguments
- *         NULL on failure
+ * \return path using platform specific delimiters on success
+ * \return `NULL` on invalid arguments
+ * \return `NULL` on failure
  */
 RCUTILS_PUBLIC
 char *
@@ -156,12 +156,11 @@ rcutils_to_native_path(
  * openat(2) documentation.
  *
  * \param[in] abs_path
- * \param[in] allocator
- * \return bool True if making the directory was successful, False otherwise
- *              False if path is NULL
- *              False if path is empty
- *              False if path is not absolute
- *              False if any intermediate directories don't exist
+ * \return `True` if making the directory was successful, False otherwise
+ * \return `False` if path is NULL
+ * \return `False` if path is empty
+ * \return `False` if path is not absolute
+ * \return `False` if any intermediate directories don't exist
  */
 RCUTILS_PUBLIC
 bool

include/rcutils/logging.h

@@ -88,7 +88,7 @@ extern bool g_rcutils_logging_initialized;
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param allocator rcutils_allocator_t to be used.
+ * \param[in] allocator rcutils_allocator_t to be used.
  * \return `RCUTILS_RET_OK` if successful.
  * \return `RCUTILS_RET_INVALID_ARGUMENT` if the allocator is invalid, in which
  *   case initialization will fail.
@@ -200,12 +200,12 @@ rcutils_logging_severity_level_from_string(
 
 /// The function signature to log messages.
 /**
- * \param location The pointer to the location struct
- * \param severity The severity level
- * \param name The name of the logger
- * \param timestamp The timestamp
- * \param format The format string
- * \param args The variable argument list
+ * \param[in] location The pointer to the location struct
+ * \param[in] severity The severity level
+ * \param[in] name The name of the logger
+ * \param[in] timestamp The timestamp
+ * \param[in] format The format string
+ * \param[in] args The variable argument list
  */
 typedef void (* rcutils_logging_output_handler_t)(
   const rcutils_log_location_t *,  // location
@@ -246,7 +246,7 @@ rcutils_logging_output_handler_t rcutils_logging_get_output_handler();
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param function The function pointer of the output handler to be used.
+ * \param[in] function The function pointer of the output handler to be used.
  */
 RCUTILS_PUBLIC
 void rcutils_logging_set_output_handler(rcutils_logging_output_handler_t function);
@@ -266,12 +266,12 @@ void rcutils_logging_set_output_handler(rcutils_logging_output_handler_t functio
  *
  * \return `RCUTILS_RET_OK` if successful.
  * \return `RCUTILS_RET_BAD_ALLOC` if memory allocation error occured
- * \param location The location information about where the log came from
- * \param severity The severity of the log message expressed as an integer
- * \param name The name of the logger that this message came from
- * \param timestamp The time at which the log message was generated
- * \param msg The message being logged
- * \param args The list of arguments to insert into the formatted log messgae
+ * \param[in] location The location information about where the log came from
+ * \param[in] severity The severity of the log message expressed as an integer
+ * \param[in] name The name of the logger that this message came from
+ * \param[in] timestamp The time at which the log message was generated
+ * \param[in] msg The message being logged
+ * \param[in] args The list of arguments to insert into the formatted log messgae
  * \param[out] logging_output An output buffer for the formatted message
  */
 RCUTILS_PUBLIC
@@ -321,7 +321,7 @@ int rcutils_logging_get_default_logger_level();
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param level The level to be used.
+ * \param[in] level The level to be used.
  */
 RCUTILS_PUBLIC
 void rcutils_logging_set_default_logger_level(int level);
@@ -340,7 +340,7 @@ void rcutils_logging_set_default_logger_level(int level);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param name The name of the logger, must be null terminated c string
+ * \param[in] name The name of the logger, must be null terminated c string
  * \return The level of the logger if it has been set, or
  * \return `RCUTILS_LOG_SEVERITY_UNSET` if unset, or
  * \return `g_rcutils_logging_default_logger_level` for an empty name, or
@@ -364,8 +364,8 @@ int rcutils_logging_get_logger_level(const char * name);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param name The name of the logger
- * \param name_length Logger name length
+ * \param[in] name The name of the logger
+ * \param[in] name_length Logger name length
  * \return The level of the logger if it has been set, or
  * \return `RCUTILS_LOG_SEVERITY_UNSET` if unset, or
  * \return `g_rcutils_logging_default_logger_level` for `name_length` of `0`, or
@@ -389,8 +389,8 @@ int rcutils_logging_get_logger_leveln(const char * name, size_t name_length);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param name The name of the logger, must be null terminated c string.
- * \param level The level to be used.
+ * \param[in] name The name of the logger, must be null terminated c string.
+ * \param[in] level The level to be used.
  * \return `RCUTILS_RET_OK` if successful, or
  * \return `RCUTILS_RET_INVALID_ARGUMENT` on invalid arguments, or
  * \return `RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID` if severity map invalid, or
@@ -410,8 +410,8 @@ rcutils_ret_t rcutils_logging_set_logger_level(const char * name, int level);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param name The name of the logger, must be null terminated c string or NULL.
- * \param severity The severity level.
+ * \param[in] name The name of the logger, must be null terminated c string or NULL.
+ * \param[in] severity The severity level.
  *
  * \return true if the logger is enabled for the level; false otherwise.
  */
@@ -438,7 +438,7 @@ bool rcutils_logging_logger_is_enabled_for(const char * name, int severity);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param name The name of the logger, must be null terminated c string.
+ * \param[in] name The name of the logger, must be null terminated c string.
  *
  * \return The level, or
  * \return -1 on invalid arguments, or
@@ -462,11 +462,11 @@ int rcutils_logging_get_logger_effective_level(const char * name);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param location The pointer to the location struct or NULL
- * \param severity The severity level
- * \param name The name of the logger, must be null terminated c string or NULL
- * \param format The format string
- * \param ... The variable arguments
+ * \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 or NULL
+ * \param[in] format The format string
+ * \param[in] ... The variable arguments
  */
 RCUTILS_PUBLIC
 void rcutils_log(
@@ -496,11 +496,11 @@ RCUTILS_ATTRIBUTE_PRINTF_FORMAT(4, 5);
  * Uses Atomics       | No
  * Lock-Free          | Yes
  *
- * \param location The pointer to the location struct or NULL
- * \param severity The severity level
- * \param name The name of the logger, must be null terminated c string
- * \param timestamp The timestamp for when the log message was made
- * \param log_str The string to be logged
+ * \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] log_str The string to be logged
  */
 RCUTILS_PUBLIC
 void rcutils_logging_console_output_handler(

include/rcutils/macros.h

@@ -85,8 +85,8 @@ extern "C"
  *
  * IMPORTANT: the first argument has an index of ONE (not zero!).
  *
- * \param format_string_index index of the format string passed to the function
- * \param first_to_check_index index of the first "optional argument"
+ * \param[in] format_string_index index of the format string passed to the function
+ * \param[in] first_to_check_index index of the first "optional argument"
  */
 #define RCUTILS_ATTRIBUTE_PRINTF_FORMAT(format_string_index, first_to_check_index) \
   __attribute__ ((format(printf, format_string_index, first_to_check_index)))

include/rcutils/types/array_list.h

@@ -36,7 +36,7 @@ typedef struct RCUTILS_PUBLIC_TYPE rcutils_array_list_t
 
 /**
  * Validates that an rcutils_array_list_t* points to a valid array list.
- * \param array_list A pointer to an rcutils_array_list_t
+ * \param[in] array_list A pointer to an rcutils_array_list_t
  * \return RCUTILS_RET_INVALID_ARGUMENT if array_list is null
  * \return RCUTILS_RET_NOT_INITIALIZED if array_list is not initialized
  */