Doxygen setup (#88)

* basic doxygen configuration

* fix up documentation and add main page

* change default value of PROJECT_NUMBER

* generalize

* avoid displaying RMW_* function macros

* remove unnecessary section

rmw/.gitignore

@@ -0,0 +1 @@
+doc_output

rmw/Doxyfile

@@ -0,0 +1,25 @@
+# All settings not listed here will use the Doxygen default values.
+
+PROJECT_NAME           = "rmw"
+PROJECT_NUMBER         = master
+PROJECT_BRIEF          = "C API providing a middleware abstraction layer which is used to implement the rest of ROS."
+
+INPUT                  = ./include
+RECURSIVE              = YES
+OUTPUT_DIRECTORY       = doc_output
+
+EXTRACT_ALL            = YES
+SORT_MEMBER_DOCS       = NO
+
+GENERATE_LATEX         = NO
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             += RMW_PUBLIC=
+PREDEFINED             += RMW_WARN_UNUSED=
+
+# Tag files that do not exist will produce a warning and cross-project linking will not work.
+TAGFILES += "../../../../doxygen_tag_files/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
+# Uncomment to generate tag files for cross-project linking.
+#GENERATE_TAGFILE = "../../../../doxygen_tag_files/rmw.tag"

rmw/include/rmw/error_handling.h

@@ -34,13 +34,16 @@ typedef struct rmw_error_state_t
   size_t line_number;
 } rmw_error_state_t;
 
-/// Set the error message, the file it occurred in, and the line on which it occurred.
+/// 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.
+ * 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 interal error storage and must be null terminated.
- * The file parameter is not copied, but instead is assumed to be a global as it should be set to
- * the __FILE__ preprocessor literal when used with the RMW_SET_ERROR_MSG macro.
+ * The error_msg parameter is copied into the internal error storage and must
+ * be null terminated.
+ * The file parameter is not copied, but instead is assumed to be a global as
+ * it should be set to the __FILE__ preprocessor literal when used with the
+ * RMW_SET_ERROR_MSG() macro.
  * It should also be null terminated.
  *
  * \param error_msg The error message to set.
@@ -51,47 +54,48 @@ RMW_PUBLIC
 void
 rmw_set_error_state(const char * error_msg, const char * file, size_t line_number);
 
-/// Set the error message, automatically appending the current file and line number.
+/// 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
- * since, and this library was built with RMW_REPORT_ERROR_HANDLING_ERRORS set
- * on, then 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.
+ * If an error message was previously set, and rmw_reset_error() was not called
+ * afterwards, and this library was built with RMW_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 msg The error message to be set.
  */
 #define RMW_SET_ERROR_MSG(msg) rmw_set_error_state(msg, __FILE__, __LINE__);
 
-/// Return true if the error has been set and has not been reset since, otherwise false.
+/// Return `true` if the error is set, otherwise `false`.
 RMW_PUBLIC
 bool
 rmw_error_is_set(void);
 
-/// Return a struct with the error message and the file and line number on which is was set.
+/// Return an rmw_error_state_t which was set with rmw_set_error_state().
 /**
  * The returned pointer will be NULL if no error has been set in this thread.
  *
- * The returned pointer is valid until RMW_SET_ERROR_MSG, rmw_set_error_state, or rmw_reset_error
- * are called in the same thread.
+ * The returned pointer is valid until RMW_SET_ERROR_MSG, rmw_set_error_state,
+ * or rmw_reset_error are called in the same thread.
  *
  * \return A pointer to the current error state struct.
  */
 RMW_PUBLIC
 const rmw_error_state_t *
 rmw_get_error_state(void);
 
-/// Return the error message followed by ', at <file>:<line>' if set, else NULL.
+/// Return the error message followed by `, at <file>:<line>`, or `NULL`.
 /**
- * The returned pointer is valid until RMW_SET_ERROR_MSG, rmw_set_error_state, or rmw_reset_error
- * are called in the same thread.
+ * The returned pointer is valid until RMW_SET_ERROR_MSG(),
+ * rmw_set_error_state(), or rmw_reset_error() are called from the same thread.
  *
- * \return The current error string, with file and line number, or NULL if not set.
+ * \return The current formatted error string, or NULL if not set.
  */
 RMW_PUBLIC
 const char *
 rmw_get_error_string(void);
 
-/// Return the error message followed by ', at <file>:<line>' if set, else "error not set".
+/// Return the error message followed by `, at <file>:<line>` if set, else "error not set".
 /**
  * This function is guaranteed to return a valid c-string.
  *

rmw/include/rmw/impl/cpp/demangle.hpp

@@ -33,6 +33,7 @@ namespace impl
 namespace cpp
 {
 
+/// Return the demangle name of the instance of type T.
 template<typename T>
 std::string
 demangle(const T & instance)

rmw/include/rmw/rmw.h

@@ -12,6 +12,49 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/** \mainpage rmw: ROS Middleware Abstraction Interface
+ *
+ * `rmw` defines an interface of middleware primitives that are used by the higher level ROS API's.
+ * It consists of these main components:
+ *
+ * - Nodes
+ *   - rmw/rmw.h
+ * - Publisher
+ *   - rmw/rmw.h
+ * - Subscription
+ *   - rmw/rmw.h
+ * - Service Client
+ *   - rmw/rmw.h
+ * - Service Server
+ *   - rmw/rmw.h
+ *
+ * It also has some machinery that is necessary to wait on and act on these concepts:
+ *
+ * - Initialization and shutdown management (global for now)
+ *   - rmw/rmw.h
+ * - Wait sets for waiting on messages and service requests / responses to be ready
+ *   - rmw/rmw.h
+ * - Guard conditions for waking up wait sets asynchronously
+ *   - rmw/rmw.h
+ *
+ * Further still there are some useful abstractions and utilities:
+ *
+ * - Allocator functions for various types
+ *   - rmw/allocators.h
+ * - Error handling functionality (C style)
+ *   - rmw/error_handling.h
+ * - Macros
+ *   - rmw/macros.h
+ * - Return code types and other utility types
+ *   - rmw/types.h
+ * - Sanity checks for some of the types
+ *   - rmw/sanity_checks.h
+ * - Macros for controlling symbol visibility on the library
+ *   - rmw/visibility_control.h
+ * - Utility function to demangle a type to a human readable string (C++ specific):
+ *   - rmw/impl/cpp/demangle.hpp
+ */
+
 #ifndef RMW__RMW_H_
 #define RMW__RMW_H_
 
@@ -53,25 +96,31 @@ rmw_ret_t
 rmw_destroy_node(rmw_node_t * node);
 
 /// Return a guard condition which is triggered when the ROS graph changes.
-/* The handle returned is a pointer to an internally held rmw guard condition.
- * This function can fail, and therefore return NULL, if:
- *   - node is NULL
+/**
+ * The handle returned is a pointer to an internally held rmw guard condition.
+ * This function can fail, and therefore return `NULL`, if:
+ *   - node is `NULL`
  *   - node is invalid
  *
  * The returned handle is made invalid if the node is destroyed or if
  * rmw_shutdown() is called.
  *
- * The guard condition will be triggered anytime a change to the ROS graph occurs.
+ * The guard condition will be triggered anytime a change to the ROS graph
+ * occurs.
  * A ROS graph change includes things like (but not limited to) a new publisher
  * advertises, a new subscription is created, a new service becomes available,
  * a subscription is canceled, etc.
  *
- * This function does not manipulate heap memory.
- * This function is thread-safe.
- * This function is lock-free.
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | No
+ * Thread-Safe        | Yes
+ * Uses Atomics       | No
+ * Lock-Free          | Yes
  *
  * \param[in] node pointer to the rmw node
- * \return rmw guard condition handle if successful, otherwise NULL
+ * \return rmw guard condition handle if successful, otherwise `NULL`
  *
  */
 RMW_PUBLIC
@@ -206,11 +255,13 @@ rmw_trigger_guard_condition(const rmw_guard_condition_t * guard_condition);
 
 /// Create a waitset to store conditions that the middleware will block on.
 /**
- * If max_conditions is 0, the waitset can store an unbounded number of conditions to wait on.
- * If max_conditions is greater than 0, the number of conditions that can be attached to the
- * waitset is bounded at max_conditions.
- * \param[in] max_conditions The maximum number of conditions that can be attached to the waitset.
- * \return A pointer to the created waitset, nullptr if an error occurred.
+ * If `max_conditions` is `0`, the waitset can store an unbounded number of
+ * conditions to wait on.
+ * If `max_conditions` is greater than `0`, the number of conditions that can
+ * be attached to the waitset is bounded at `max_conditions`.
+ * \param[in] max_conditions
+ *   The maximum number of conditions that can be attached to the waitset.
+ * \return A pointer to the created waitset, `NULL` if an error occurred.
  */
 RMW_PUBLIC
 RMW_WARN_UNUSED
@@ -222,32 +273,39 @@ RMW_WARN_UNUSED
 rmw_ret_t
 rmw_destroy_waitset(rmw_waitset_t * waitset);
 
+/// Waits on sets of different waitable entities and returns when one is ready.
 /**
- * Add conditions to the wait set and wait until a response comes in, or until the timeout is
- * reached.
+ * Add conditions to the wait set and wait until a response comes in, or until
+ * the timeout is reached.
  * The arrays contain type-erased representations of waitable entities.
- * This function casts the pointers to middleware-specific conditions and adds them to the
- * waitset.
+ * This function casts the pointers to middleware-specific conditions and adds
+ * them to the waitset.
  *
- * The count variables in the arrays represents the number of valid pointers in the array.
- * Null pointers are in the array considered invalid. If they are encountered, an error is
- * returned.
+ * The count variables in the arrays represents the number of valid pointers
+ * in the array.
+ * `NULL` pointers are in the array considered invalid.
+ * If they are encountered, an error is returned.
  *
  * The array structs are allocated and deallocated outside of this function.
- * They do not have any information about how much memory is allocated for the arrays.
+ * They do not have any information about how much memory is allocated for the
+ * arrays.
  *
- * After the wait wakes up, the entries in each array that correspond to conditions that were
- * not triggered are set to null.
+ * After the wait wakes up, the entries in each array that correspond to
+ * conditions that were not triggered are set to `NULL`.
  *
  * \param subscriptions Array of subscriptions to wait on
  * \param guard_conditions Array of guard conditions to wait on
  * \param services Array of services to wait on
  * \param clients Array of clients to wait on
  * \param waitset Storage for the waitset
- * \param wait_timeout If negative, block indefinitely or until a condition is ready.
- * If zero,  check only for immediately available conditions and don't block.
- * Else, this represents the maximum time to wait for a response from the waitset.
- * \return RMW_RET_OK if success, RMW_RET_ERROR if error, RMW_RET_TIMEOUT if wait timed out.
+ * \param wait_timeout
+ *   If negative, block indefinitely or until a condition is ready.
+ *   If zero, check only for immediately available conditions and don't block.
+ *   Else, this represents the maximum time to wait for a response from the
+ *   waitset.
+ * \return `RMW_RET_OK` if success, or
+ * \return `RMW_RET_ERROR` if error, or
+ * \return `RMW_RET_TIMEOUT` if wait timed out.
  */
 RMW_PUBLIC
 RMW_WARN_UNUSED
@@ -300,17 +358,19 @@ rmw_ret_t
 rmw_compare_gids_equal(const rmw_gid_t * gid1, const rmw_gid_t * gid2, bool * result);
 
 /// Check if a service server is available for the given service client.
-/* This function will return true for is_available if there is a service server
- * available for the given client.
+/**
+ * This function will return true for `is_available` if there is a service
+ * server available for the given client.
  *
- * The node parameter must not be NULL, and must point to a valid node.
+ * The node parameter must not be `NULL`, and must point to a valid node.
  *
- * The client parameter must not be NULL, and must point to a valid client.
+ * The client parameter must not be `NULL`, and must point to a valid client.
  *
  * The given client and node must match, i.e. the client must have been created
  * using the given node.
  *
- * The is_available parameter must not be NULL, and must point to a bool variable.
+ * The is_available parameter must not be `NULL`, and must point to a bool
+ * variable.
  * The result of the check will be stored in the is_available parameter.
  *
  * This function does manipulate heap memory.
@@ -319,9 +379,10 @@ rmw_compare_gids_equal(const rmw_gid_t * gid1, const rmw_gid_t * gid2, bool * re
  *
  * \param[in] node the handle to the node being used to query the ROS graph
  * \param[in] client the handle to the service client being queried
- * \param[out] is_available set to true if there is a service server available, else false
- * \return RMW_RET_OK if node the check was made successfully, or
- *         RCL_RET_ERROR if an unspecified error occurs.
+ * \param[out] is_available
+ *   set to true if there is a service server available, else false
+ * \return `RMW_RET_OK` if node the check was made successfully, or
+ * \return `RMW_RET_ERROR` if an unspecified error occurs.
  */
 RMW_PUBLIC
 RMW_WARN_UNUSED

rmw/include/rmw/sanity_checks.h

@@ -24,7 +24,7 @@ extern "C"
 #include "rmw/types.h"
 #include "rmw/visibility_control.h"
 
-/// Check that a rmw_topic_names_and_types_t struct is zero initialized
+/// Check that a rmw_topic_names_and_types_t struct is zero initialized.
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_ret_t