Add API documentation and Doxyfile for tracetools

Signed-off-by: Christophe Bedard <bedard.christophe@gmail.com>

Change title

Signed-off-by: Christophe Bedard <bedard.christophe@gmail.com>

tracetools/.gitignore

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

tracetools/Doxyfile

@@ -0,0 +1,32 @@
+# All settings not listed here will use the Doxygen default values.
+# To use, see: https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing-api
+
+PROJECT_NAME           = "tracetools"
+PROJECT_NUMBER         = $(PROJECT_NUMBER)
+PROJECT_BRIEF          = "Tracing tools and instrumentation for ROS 2"
+
+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     = NO
+PREDEFINED             = \
+    "TRACETOOLS_PUBLIC="
+
+EXCLUDE_SYMBOLS        = \
+    "DECLARE_TRACEPOINT" \
+    "_demangle_symbol" \
+    "_get_symbol_funcptr"
+
+# Tag files that do not exist will produce a warning and cross-project linking will not work.
+TAGFILES += "../../../data/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
+# Uncomment to generate tag files for cross-project linking.
+GENERATE_TAGFILE = "../../../data/tracetools.tag"

tracetools/include/tracetools/tracetools.h

@@ -12,6 +12,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/** \mainpage tracetools: tracing tools and instrumentation for ROS 2
+ *
+ * `tracetools` provides utilities to instrument ROS.
+ * It provides two main headers:
+ *
+ * - tracetools/tracetools.h
+ *   - instrumentation functions
+ * - tracetools/utils.hpp
+ *   - utility functions
+ */
+
 #ifndef TRACETOOLS__TRACETOOLS_H_
 #define TRACETOOLS__TRACETOOLS_H_
 
@@ -22,10 +33,14 @@
 #include "tracetools/visibility_control.hpp"
 
 #ifndef TRACETOOLS_DISABLED
+/// Call a tracepoint.
+/**
+ * This is the preferred method over calling the actual function directly.
+ */
 #  define TRACEPOINT(event_name, ...) \
   (ros_trace_ ## event_name)(__VA_ARGS__)
 #  define DECLARE_TRACEPOINT(event_name, ...) \
-  TRACETOOLS_PUBLIC void(ros_trace_ ## event_name)(__VA_ARGS__);
+  TRACETOOLS_PUBLIC void ros_trace_ ## event_name(__VA_ARGS__);
 #else
 #  define TRACEPOINT(event_name, ...) ((void) (0))
 #  define DECLARE_TRACEPOINT(event_name, ...)
@@ -36,20 +51,32 @@ extern "C"
 {
 #endif
 
+/// Get tracing compilation status.
 /**
- * Report whether tracing is compiled in
+ * \return `true` if tracing is enabled, `false` otherwise
  */
 TRACETOOLS_PUBLIC bool ros_trace_compile_status();
 
+/// `rcl_init`
 /**
- * tp: rcl_init
+ * Initialisation for the whole process.
+ * Notes the `tracetools` version automatically.
+ *
+ * \param[in] context_handle pointer to the `rcl_context_t` handle
  */
 DECLARE_TRACEPOINT(
   rcl_init,
   const void * context_handle)
 
+/// `rcl_node_init`
 /**
- * tp: rcl_node_init
+ * Node initialisation.
+ * Links a `rcl_node_t` handle to its `rmw_node_t` handle.
+ *
+ * \param[in] node_handle pointer to the node's `rcl_node_t` handle
+ * \param[in] rmw_handle pointer to the node's `rmw_node_t` handle
+ * \param[in] node_name node name
+ * \param[in] node_namespace node namespace
  */
 DECLARE_TRACEPOINT(
   rcl_node_init,
@@ -58,8 +85,17 @@ DECLARE_TRACEPOINT(
   const char * node_name,
   const char * node_namespace)
 
+/// `rcl_publisher_init`
 /**
- * tp: rcl_publisher_init
+ * Publisher initialisation.
+ * Links a `rcl_publisher_t` handle to its `rcl_node_t` handle
+ * and its `rmw_publisher_t` handle, and links it to a topic name.
+ *
+ * \param[in] publisher_handle pointer to the publisher's `rcl_publisher_t` handle
+ * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the publisher belongs to
+ * \param[in] rmw_publisher_handle pointer to the publisher's `rmw_publisher_t` handle
+ * \param[in] topic_name full topic name
+ * \param[in] queue_depth publisher history depth
  */
 DECLARE_TRACEPOINT(
   rcl_publisher_init,
@@ -69,8 +105,18 @@ DECLARE_TRACEPOINT(
   const char * topic_name,
   const size_t queue_depth)
 
+/// `rcl_subscription_init`
 /**
- * tp: rcl_subscription_init
+ * Subscription initialisation.
+ * Links a `rcl_subscription_t` handle to its `rcl_node_t` handle
+ * and its `rmw_subscription_t` handle, and links it to a topic name.
+ *
+ * \param[in] subscription_handle pointer to the subscription's `rcl_subscription_t` handle
+ * \param[in] node_handle
+ *  pointer to the `rcl_node_t` handle of the node the subscription belongs to
+ * \param[in] rmw_subscription_handle pointer to the subscription's `rmw_subscription_t` handle
+ * \param[in] topic_name full topic name
+ * \param[in] queue_depth subscription history depth
  */
 DECLARE_TRACEPOINT(
   rcl_subscription_init,
@@ -80,24 +126,44 @@ DECLARE_TRACEPOINT(
   const char * topic_name,
   const size_t queue_depth)
 
+/// `rclcpp_subscription_init`
 /**
- * tp: rclcpp_subscription_init
+ * Subscription object initialisation.
+ * Links the `rclcpp::*Subscription*` object to a `rcl_subscription_t` handle.
+ * Needed since there could be more than 1 `rclcpp::*Subscription*` object
+ * for one `rcl` subscription (e.g. when using intra-process).
+ *
+ * \param[in] subscription_handle
+ *  pointer to the `rcl_subscription_t` handle of the subscription this object belongs to
+ * \param[in] subscription pointer to this subscription object (e.g. `rclcpp::*Subscription*`)
  */
 DECLARE_TRACEPOINT(
   rclcpp_subscription_init,
   const void * subscription_handle,
   const void * subscription)
 
+/// `rclcpp_subscription_callback_added`
 /**
- * tp: rclcpp_subscription_callback_added
+ * Link a subscription callback object to a subscription object.
+ *
+ * \param[in] subscription pointer to the subscription object this callback belongs to
+ * \param[in] callback pointer to this callback object (e.g. `rclcpp::AnySubscriptionCallback`)
  */
 DECLARE_TRACEPOINT(
   rclcpp_subscription_callback_added,
   const void * subscription,
   const void * callback)
 
+/// `rcl_service_init`
 /**
- * tp: rcl_service_init
+ * Service initialisation.
+ * Links a `rcl_service_t` handle to its `rcl_node_t` handle
+ * and its `rmw_service_t` handle, and links it to a service name.
+ *
+ * \param[in] service_handle pointer to the service's `rcl_service_t` handle
+ * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the service belongs to
+ * \param[in] rmw_service_handle pointer to the service's `rmw_service_t` handle
+ * \param[in] service_name full service name
  */
 DECLARE_TRACEPOINT(
   rcl_service_init,
@@ -106,16 +172,29 @@ DECLARE_TRACEPOINT(
   const void * rmw_service_handle,
   const char * service_name)
 
+/// `rclcpp_service_callback_added`
 /**
- * tp: rclcpp_service_callback_added
+ * Link a service callback object to a service.
+ *
+ * \param[in] service_handle
+ *  pointer to the `rcl_service_t` handle of the service this callback belongs to
+ * \param[in] callback pointer to this callback object (e.g. `rclcpp::AnyServiceCallback`)
  */
 DECLARE_TRACEPOINT(
   rclcpp_service_callback_added,
   const void * service_handle,
   const void * callback)
 
+/// `rcl_client_init`
 /**
- * tp: rcl_client_init
+ * Client initialisation.
+ * Links a `rcl_client_t` handle to its `rcl_node_t` handle
+ * and its `rmw_client_t` handle, and links it to a client name.
+ *
+ * \param[in] client_handle pointer to the client's `rcl_client_t` handle
+ * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the client belongs to
+ * \param[in] rmw_client_handle pointer to the client's `rmw_client_t` handle
+ * \param[in] service_name full client name
  */
 DECLARE_TRACEPOINT(
   rcl_client_init,
@@ -124,40 +203,68 @@ DECLARE_TRACEPOINT(
   const void * rmw_client_handle,
   const char * service_name)
 
+/// `rcl_timer_init`
 /**
- * tp: rcl_timer_init
+ * Timer initialisation.
+ * Notes the timer's period.
+ *
+ * \param[in] timer_handle pointer to the timer's `rcl_timer_t` handle
+ * \param[in] period period in nanoseconds
  */
 DECLARE_TRACEPOINT(
   rcl_timer_init,
   const void * timer_handle,
   int64_t period)
 
+/// `rclcpp_timer_callback_added`
 /**
- * tp: rclcpp_timer_callback_added
+ * Link a timer callback object to its `rcl_timer_t` handle.
+ *
+ * \param[in] timer_handle
+ *  pointer to the `rcl_timer_t` handle of the timer this callback belongs to
+ * \param[in] callback pointer to the callback object (`std::function`)
  */
 DECLARE_TRACEPOINT(
   rclcpp_timer_callback_added,
   const void * timer_handle,
   const void * callback)
 
+/// `rclcpp_callback_register`
 /**
- * tp: rclcpp_callback_register
+ * Register a demangled function symbol with a callback.
+ *
+ * \param[in] callback pointer to the callback object
+ *  (e.g. `rclcpp::AnySubscriptionCallback`,
+ *  `rclcpp::AnyServiceCallback`, timer `std::function`, etc.)
+ * \param[in] function_symbol demangled symbol of the callback function/lambda,
+ *  see \ref get_symbol()
  */
 DECLARE_TRACEPOINT(
   rclcpp_callback_register,
   const void * callback,
   const char * function_symbol)
 
+/// `callback_start`
 /**
- * tp: callback_start
+ * Start of a callback.
+ *
+ * \param[in] callback pointer to this callback object
+ *  (e.g. `rclcpp::AnySubscriptionCallback`,
+ *  `rclcpp::AnyServiceCallback`, timer `std::function`, etc.)
+ * \param[in] is_intra_process whether this callback is done via intra-process or not
  */
 DECLARE_TRACEPOINT(
   callback_start,
   const void * callback,
   const bool is_intra_process)
 
+/// `callback_end`
 /**
- * tp: callback_end
+ * End of a callback.
+ *
+ * \param[in] callback pointer to this callback object
+ *  (e.g. `rclcpp::AnySubscriptionCallback`,
+ *  `rclcpp::AnyServiceCallback`, timer `std::function`, etc.)
  */
 DECLARE_TRACEPOINT(
   callback_end,

tracetools/include/tracetools/utils.hpp

@@ -20,12 +20,21 @@
 
 #include "tracetools/visibility_control.hpp"
 
+/// Default symbol, used when address resolution fails.
 #define SYMBOL_UNKNOWN "UNKNOWN"
 
 TRACETOOLS_PUBLIC const char * _demangle_symbol(const char * mangled);
 
 TRACETOOLS_PUBLIC const char * _get_symbol_funcptr(void * funcptr);
 
+/// Get symbol from an std::function object.
+/**
+ * If function address resolution or symbol demangling fails,
+ * this will return a string that starts with \ref SYMBOL_UNKNOWN.
+ *
+ * \param[in] f the std::function object
+ * \return the symbol, or a placeholder
+ */
 template<typename T, typename ... U>
 const char * get_symbol(std::function<T(U...)> f)
 {
@@ -40,7 +49,13 @@ const char * get_symbol(std::function<T(U...)> f)
   return _demangle_symbol(f.target_type().name());
 }
 
-// Fallback meant for lambdas with captures
+/// Get symbol from a function-related object.
+/**
+ * Fallback meant for lambdas with captures.
+ *
+ * \param[in] l a generic object
+ * \return the symbol
+ */
 template<typename L>
 const char * get_symbol(L && l)
 {