Adding doxygen documentation and READMEs to packages (#204)

* Adding doxygen documentation and READMEs to packages

Signed-off-by: Stephen Brawner <brawner@gmail.com>

* PR Fixup

Signed-off-by: Stephen Brawner <brawner@gmail.com>

* Fixing merge with master

Signed-off-by: Stephen Brawner <brawner@gmail.com>

rmw/README.md

@@ -0,0 +1,8 @@
+# RMW
+
+The ROS 2 Middleware Interface provides an abstraction layer to different DDS implementations for communication with the ROS 2 Client Library. This package contains the `rmw` interface for DDS implementation and some general functionality useful for implementers.
+
+For more information, see https://design.ros2.org/articles/ros_middleware_interface.html
+
+## Interface and Features
+For specific information about the rmw interface and features, see its [api docs](http://docs.ros2.org/latest/api/rmw/).

rmw/include/rmw/allocators.h

@@ -23,66 +23,131 @@ extern "C"
 #include "rmw/types.h"
 #include "rmw/visibility_control.h"
 
+/// Allocate memory of size in bytes using rcutils default allocator's allocate()
+/**
+ * \param[in] size The number of bytes to allocate
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 void *
 rmw_allocate(size_t size);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_free(void * pointer);
 
+/// Allocate memory for an `rmw_node_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_node_t *
 rmw_node_allocate(void);
 
+/// Free memory allocated to this node pointer using rcutils default allocator's deallocate()
+/**
+ * \param[in] pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_node_free(rmw_node_t * node);
 
+/// Allocate memory for an `rmw_publisher_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_publisher_t *
 rmw_publisher_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_publisher_free(rmw_publisher_t * publisher);
 
+/// Allocate memory for an `rmw_subscription_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_subscription_t *
 rmw_subscription_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_subscription_free(rmw_subscription_t * subscription);
 
+/// Allocate memory for an `rmw_guard_condition_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_guard_condition_t *
 rmw_guard_condition_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_guard_condition_free(rmw_guard_condition_t * guard_condition);
 
+/// Allocate memory for an `rmw_client_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_client_t *
 rmw_client_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_client_free(rmw_client_t * client);
 
+/// Allocate memory for an `rmw_service_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_service_t *
 rmw_service_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_service_free(rmw_service_t * service);
 
+/// Allocate memory for an `rmw_wait_set_t` using rcutils default allocator's allocate()
+/**
+ * \return pointer to allocated memory
+ */
 RMW_PUBLIC
 rmw_wait_set_t *
 rmw_wait_set_allocate(void);
 
+/// Free memory using rcutils default allocator's deallocate()
+/**
+ * \param[in] size pointer to allocated memory
+ */
 RMW_PUBLIC
 void
 rmw_wait_set_free(rmw_wait_set_t * wait_set);

rmw/include/rmw/convert_rcutils_ret_to_rmw_ret.h

@@ -25,6 +25,11 @@ extern "C"
 #include "rmw/types.h"
 #include "rmw/visibility_control.h"
 
+/// Map a `rcutil_ret_t` value to the equivalent `rmw_ret_t` value
+/**
+ * \param[in] rcutils_ret The rcutils type to map
+ * \return rmw_ret_t result mapped value, or RMW_RET_ERROR if the rcutils_ret value is not supported
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_ret_t

rmw/include/rmw/error_handling.h

@@ -12,6 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * @file error_handling.h
+ * @brief Functions and macros to interact with error handling mechanisms
+ *
+ * This logic pretty much renames many `rcutils` functions and macros. Also check out that
+ * package's documentation for more information.
+ */
+
 #ifndef RMW__ERROR_HANDLING_H_
 #define RMW__ERROR_HANDLING_H_
 
@@ -22,33 +30,149 @@ extern "C"
 
 #include <rcutils/error_handling.h>
 
+/// Struct wrapping a fixed-size c string used for returning the formatted error string.
 typedef rcutils_error_string_t rmw_error_string_t;
+
+/// Struct which encapsulates the error state set by RMW_SET_ERROR_MSG().
 typedef rcutils_error_state_t rmw_error_state_t;
 
+/// Limit the buffer size in the `fwrite` call to give an upper bound to buffer overrun in the case
+/// of non-null terminated `msg`.
 #define RMW_SAFE_FWRITE_TO_STDERR RCUTILS_SAFE_FWRITE_TO_STDERR
 
+/// Forces initialization of thread-local storage if called in a newly created thread.
+/**
+ * If this function is not called beforehand, then the first time the error
+ * state is set or the first time the error message is retrieved, the default
+ * allocator will be used to allocate thread-local storage.
+ *
+ * This function may or may not allocate memory.
+ * The system's thread-local storage implementation may need to allocate
+ * memory, since it usually has no way of knowing how much storage is needed
+ * without knowing how many threads will be created.
+ * Most implementations (e.g. C11, C++11, and pthread) do not have ways to
+ * specify how this memory is allocated, but if the implementation allows, the
+ * given allocator to this function will be used, but is otherwise unused.
+ * This only occurs when creating and destroying threads, which can be avoided
+ * in the "steady" state by reusing pools of threads.
+ *
+ * It is worth considering that repeated thread creation and destruction will
+ * result in repeated memory allocations and could result in memory
+ * fragmentation.
+ * This is typically avoided anyways by using pools of threads.
+ *
+ * In case an error is indicated by the return code, no error message will have
+ * been set.
+ *
+ * If called more than once in a thread, or after implicitly initialized by
+ * setting the error state, it will still return `RCUTILS_RET_OK`, even
+ * if the given allocator is invalid.
+ * Essentially this function does nothing if thread-local storage has already
+ * been called.
+ * If already initialized, the given allocator is ignored, even if it does not
+ * match the allocator used originally to initialize the thread-local storage.
+ *
+ * \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
+ * \return `RCUTILS_RET_ERROR` if an unspecified error occurs.
+ */
 #define rmw_initialize_error_handling_thread_local_storage \
   rcutils_initialize_error_handling_thread_local_storage
 
+/// Set the error message, as well as the file and line on which it occurred.
+/**
+ * This is not meant to be used directly, but instead via the
+ * RMW_SET_ERROR_MSG(msg) macro.
+ *
+ * The error_msg parameter is copied into the internal error storage and must
+ * be null terminated.
+ * The file parameter is copied into the internal error storage and must
+ * be null terminated.
+ *
+ * \param[in] error_string The error message to set.
+ * \param[in] file The path to the file in which the error occurred.
+ * \param[in] line_number The line number on which the error occurred.
+ */
 #define rmw_set_error_state rcutils_set_error_state
 
+/// Check an argument for a null value.
+/**
+ * If the argument's value is `NULL`, set the error message saying so and
+ * return the `error_return_type`.
+ *
+ * \param[in] argument The argument to test.
+ * \param[in] error_return_type The type to return if the argument is `NULL`.
+ */
 #define RMW_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type) \
   RCUTILS_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type)
 
+/// Check a value for null, with an error message and error statement.
+/**
+ * If `value` is `NULL`, the error statement will be evaluated after
+ * setting the error message.
+ *
+ * \param[in] value The value to test.
+ * \param[in] msg The error message if `value` is `NULL`.
+ * \param[in] error_statement The statement to evaluate if `value` is `NULL`.
+ */
 #define RMW_CHECK_FOR_NULL_WITH_MSG(value, msg, error_statement) \
   RCUTILS_CHECK_FOR_NULL_WITH_MSG(value, msg, error_statement)
 
+/// Set the error message, as well as append the current file and line number.
+/**
+ * If an error message was previously set, and rmw_reset_error() was not called
+ * afterwards, and this library was built with RCUTILS_REPORT_ERROR_HANDLING_ERRORS
+ * turned on, then the previously set error message will be printed to stderr.
+ * Error state storage is thread local and so all error related functions are
+ * also thread local.
+ *
+ * \param[in] msg The error message to be set.
+ */
 #define RMW_SET_ERROR_MSG(msg) RCUTILS_SET_ERROR_MSG(msg)
 
+/// Set the error message using a format string and format arguments.
+/**
+ * This function sets the error message using the given format string.
+ * The resulting formatted string is silently truncated at
+ * RCUTILS_ERROR_MESSAGE_MAX_LENGTH.
+ *
+ * \param[in] format_string The string to be used as the format of the error message.
+ * \param[in] ... Arguments for the format string.
+ */
 #define RMW_SET_ERROR_MSG_WITH_FORMAT_STRING(format_string, ...) \
   RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING(format_string, __VA_ARGS__)
 
+/// Return `true` if the error is set, otherwise `false`.
+/**
+ * This is currently defines as `rcutils_error_is_set`
+ */
 #define rmw_error_is_set rcutils_error_is_set
 
+/// Return an rcutils_error_state_t which was set with rcutils_set_error_state().
+/**
+ * The returned pointer will be NULL if no error has been set in this thread.
+ *
+ * The returned pointer is valid until RCUTILS_SET_ERROR_MSG, rcutils_set_error_state,
+ * or rcutils_reset_error are called in the same thread.
+ *
+ * \return A pointer to the current error state struct.
+ */
 #define rmw_get_error_state rcutils_get_error_state
 
+/// Return the error message followed by `, at <file>:<line>` if set, else "error not set".
+/**
+ * This function is "safe" because it returns a copy of the current error
+ * string or one containing the string "error not set" if no error was set.
+ * This ensures that the copy is owned by the calling thread and is therefore
+ * never invalidated by other error handling calls, and that the C string
+ * inside is always valid and null terminated.
+ *
+ * \return The current error string, with file and line number, or "error not set" if not set.
+ */
 #define rmw_get_error_string rcutils_get_error_string
 
+/// Reset the error state by clearing any previously set error state.
 #define rmw_reset_error rcutils_reset_error
 
 #ifdef __cplusplus

rmw/include/rmw/event.h

@@ -66,8 +66,8 @@ rmw_get_zero_initialized_event(void);
 /// Initialize a rmw publisher event.
 /**
  * \param[in|out] rmw_event to initialize
- * \param publisher to initialize with
- * \param event_type for the event to handle
+ * \param[in] publisher to initialize with
+ * \param[in|out] event_type for the event to initialize
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_INVALID_ARGUMENT` if invalid argument, or
  * \return `RMW_RET_UNSUPPORTED` if event_type is not supported, or
@@ -84,8 +84,8 @@ rmw_publisher_event_init(
 /// Initialize a rmw subscription event.
 /**
  * \param[in|out] rmw_event to initialize
- * \param subscription to initialize with
- * \param event_type for the event to handle
+ * \param[in] subscription to initialize with
+ * \param[in|out] event_type for the event to handle
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_INVALID_ARGUMENT` if invalid argument, or
  * \return `RMW_RET_UNSUPPORTED` if event_type is not supported, or
@@ -101,9 +101,9 @@ rmw_subscription_event_init(
 
 /// Take an event from the event handle.
 /**
- * \param event_handle event object to take from
- * \param event_info event info object to write taken data into
- * \param taken boolean flag indicating if an event was taken or not
+ * \param[in] event_handle event object to take from
+ * \param[in|out] event_info event info object to write taken data into
+ * \param[out] taken boolean flag indicating if an event was taken or not
  * \return `RMW_RET_OK` if successful, or
  * \return `RMW_RET_BAD_ALLOC` if memory allocation failed, or
  * \return `RMW_RET_ERROR` if an unexpected error occurs.
@@ -118,7 +118,7 @@ rmw_take_event(
 
 /// Finalize an rmw_event_t.
 /**
- * \param event to finalize
+ * \param[in] event to finalize
  */
 RMW_PUBLIC
 RMW_WARN_UNUSED

rmw/include/rmw/macros.h

@@ -17,8 +17,10 @@
 
 #include "rcutils/macros.h"
 
+/// Expand the argument to its literal text
 #define RMW_STRINGIFY(x) RCUTILS_STRINGIFY(x)
 
+/// Indicate that a variable is not used, and prevent compiler from issuing warnings
 #define RMW_WARN_UNUSED RCUTILS_WARN_UNUSED
 
 #endif  // RMW__MACROS_H_