Merge "Add doxygen to roctracer.h" into amd-staging

CMakeLists.txt

@@ -29,7 +29,7 @@ set ( CMAKE_VERBOSE_MAKEFILE TRUE CACHE BOOL "Verbose Output" FORCE )
 set ( ROCTRACER_NAME "roctracer" )
 set ( ROCTRACER_TARGET "${ROCTRACER_NAME}64" )
 set ( ROCTRACER_LIBRARY "lib${ROCTRACER_TARGET}" )
-project ( ${ROCTRACER_TARGET} )
+project ( ${ROCTRACER_TARGET} VERSION 4.0.0)
 
 ## Adding default path cmake modules
 list ( APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake_modules" )
@@ -204,3 +204,36 @@ set ( CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE "${CMAKE_CURRENT_BINARY_DIR}/RPM/post
 include ( CPack )
 
 endif()
+
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+  # set input and output files
+  set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in)
+  set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+  # request to configure the file
+  configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+  add_custom_command(
+    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/html/index.html ${CMAKE_CURRENT_BINARY_DIR}/doc/latex/refman.pdf
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+    COMMAND make -C ${CMAKE_CURRENT_BINARY_DIR}/doc/latex pdf
+    MAIN_DEPENDENCY ${DOXYGEN_OUT} ${DOXYGEN_IN}
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/inc/roctracer.h
+    COMMENT "Generating documentation")
+
+  add_custom_target(doc DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doc/html/index.html
+    ${CMAKE_CURRENT_BINARY_DIR}/doc/latex/refman.pdf)
+
+  install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/doc/latex/refman.pdf"
+    DESTINATION share/doc/roctracer
+    RENAME "roctracer.pdf"
+    OPTIONAL)
+
+  install(DIRECTORY
+    "${CMAKE_CURRENT_BINARY_DIR}/doc/html/"
+    DESTINATION share/html/roctracer
+    OPTIONAL)
+
+endif()

inc/roctracer.h

@@ -18,18 +18,23 @@
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE. */
 
-////////////////////////////////////////////////////////////////////////////////
-//
-// ROC Tracer API
-//
-// ROC-tracer library, Runtimes Generic Callback/Activity APIs.
-// The goal of the implementation is to provide a generic independent from
-// specific runtime profiler to trace API and asynchronous activity.
-//
-// The API provides functionality for registering the runtimes API callbacks and
-// asynchronous activity records pool support.
-//
-////////////////////////////////////////////////////////////////////////////////
+/** \mainpage ROC Tracer API Specification
+ *
+ * \section introduction Introduction
+ *
+ * ROC-tracer library, Runtimes Generic Callback/Activity APIs.
+ *
+ * The goal of the implementation is to provide a generic independent from
+ * specific runtime profiler to trace API and asynchronous activity.
+ *
+ * The API provides functionality for registering the runtimes API callbacks and
+ * asynchronous activity records pool support.
+*/
+
+/**
+ * \file
+ * ROC tracer API interface.
+ */
 
 #ifndef INC_ROCTRACER_H_
 #define INC_ROCTRACER_H_
@@ -42,99 +47,335 @@
 
 #include <ext/prof_protocol.h>
 
-#define ROCTRACER_VERSION_MAJOR 4
-#define ROCTRACER_VERSION_MINOR 0
-
 #ifdef __cplusplus
 extern "C" {
 #endif  // __cplusplus
 
-////////////////////////////////////////////////////////////////////////////////
-// Returning library version
+/** \defgroup versioning_group Versioning
+ *
+ * Version information about the interface and the associated installed
+ * library.
+ *
+ * The semantic version of the interface following semver.org rules. A client
+ * that uses this interface is only compatible with the installed library if
+ * the major version numbers match and the interface minor version number is
+ * less than or equal to the installed library minor version number.
+ * 
+ * @{
+ */
+
+/**
+ * The major version of the interface as a macro so it can be used by the
+ * preprocessor.
+ */
+#define ROCTRACER_VERSION_MAJOR 4
+
+/**
+ * The minor version of the interface as a macro so it can be used by the
+ * preprocessor.
+ */
+#define ROCTRACER_VERSION_MINOR 0
+
+/**
+ * Query the major version of the installed library.
+ *
+ * Return the major version of the installed library.  This can be used to
+ * check if it is compatible with this interface version.  This function can be
+ * used even when the library is not initialized.
+ */
 uint32_t roctracer_version_major();
+
+/**
+ * Query the minor version of the installed library.
+ *
+ * Return the minor version of the installed library.  This can be used to
+ * check if it is compatible with this interface version.  This function can be
+ * used even when the library is not initialized.
+ */
 uint32_t roctracer_version_minor();
 
-////////////////////////////////////////////////////////////////////////////////
-// Library errors enumeration
+/** @} */
+
+/** \defgroup status_codes_group Status Codes
+ *
+ * Most operations return a status code to indicate success or error.
+ *
+ * @{
+ */
+
+/**
+ * ROC Tracer API status codes.
+ */
 typedef enum {
+  /**
+   * The function has executed successfully.
+   */
   ROCTRACER_STATUS_SUCCESS = 0,
+  /**
+   * A generic error has occurred.
+   */
   ROCTRACER_STATUS_ERROR = 1,
   ROCTRACER_STATUS_UNINIT = 2,
   ROCTRACER_STATUS_BREAK = 3,
+  /**
+   * The domain is invalid.
+   */
   ROCTRACER_STATUS_BAD_DOMAIN = 4,
+  /**
+   * A parameter is invalid.
+   */
   ROCTRACER_STATUS_BAD_PARAMETER = 5,
+  /**
+   * An error in a HIP API domain operation.
+   */
   ROCTRACER_STATUS_HIP_API_ERR = 6,
+  /**
+   * An error in a HIP asynchronous operation domain operation.
+   */
   ROCTRACER_STATUS_HIP_OPS_ERR = 7,
   ROCTRACER_STATUS_HCC_OPS_ERR = ROCTRACER_STATUS_HIP_OPS_ERR,
+  /**
+   * An error in a HSA domain operation.
+   */
   ROCTRACER_STATUS_HSA_ERR = 7,
+  /**
+   * An error in a ROCTX domain operation.
+   */
   ROCTRACER_STATUS_ROCTX_ERR = 8,
 } roctracer_status_t;
 
-////////////////////////////////////////////////////////////////////////////////
-// Returning the last error
+/**
+ * Query the textual description of the last error for the current thread.
+ *
+ * Returns a NUL terminated string describing the error of the last ROC Tracer
+ * API call by the calling thread that did not return success.  The empty
+ * string is returned if there is no previous error.  The last error is not
+ * cleared.
+ *
+ * \return Return the error string.  The caller owns the returned string and
+ * should use \p free() to deallocate it.
+ */
 const char* roctracer_error_string();
 
-////////////////////////////////////////////////////////////////////////////////
-// Traced runtime domains
+/** @} */
 
-// Activity domain type
+/** \defgroup domain_group Traced Runtime Domains
+ *
+ * The ROC Tracer API can trace multiple runtime libraries.  Each library can
+ * have API operations and asynchronous operations that can be traced.
+ *
+ * @{
+ */
+
+/**
+ * Enumeration of domains that can be traced.
+ */
 typedef activity_domain_t roctracer_domain_t;
 
-// Return Op string by given domain and Op code
-// NULL returned on the error and the library errno is set
-const char* roctracer_op_string(uint32_t domain,  // tracing domain
-                                uint32_t op,      // activity op ID
-                                uint32_t kind);   // activity kind
+/**
+ * Query textual name of an operation of a domain.
+ *
+ * @param[in] domain Domain being queried.
+ *
+ * @param[in] op Operation within \p domain.
+ *
+ * @param[in] kind \todo Define kind.
+ *
+ * @return Returns the NUL terminated string for the operation name, or NULL if
+ * the domain or operation are invalid.  The string is owned by the ROC Tracer
+ * library.
+ */
+const char* roctracer_op_string(uint32_t domain,
+                                uint32_t op,
+                                uint32_t kind);
 
-// Return Op code and kind by given string
-roctracer_status_t roctracer_op_code(uint32_t domain,  // tracing domain
-                                     const char* str,  // [in] op string
-                                     uint32_t* op,     // [out] op code
-                                     uint32_t* kind);  // [out] op kind code if not NULL
+/**
+ * Query the operation code given a domain and the name of an operation.
+ *
+ * @param[in] domain The domain being queried.
+ *
+ * @param[in] str The NUL terminated name of the operation name being queried.
+ *
+ * @param[out] op The operation code.
+ *
+ * @param[out] kind If not NULL then the operation kind code.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.  \p op and \p kind have been updated.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_PARAMETER Then \p op is invalid for \p domain.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_DOMAIN The domain is invalid or not supported.
+ */
+roctracer_status_t roctracer_op_code(uint32_t domain,
+                                     const char* str,
+                                     uint32_t* op,
+                                     uint32_t* kind);
 
-////////////////////////////////////////////////////////////////////////////////
-// Callback API
-//
-// ROC tracer provides support for runtime API callbacks and activity
-// records logging. The API callbacks provide the API calls arguments and are
-// called on different phases, on enter, on exit, on kernel completion.
-// Methods return non-zero on error and library errno is set.
+/**
+ * Set the properties of a domain.
+ *
+ * @param[in] domain The domain.
+ *
+ * @param[in] properties The properties. Each domain defines its own type for
+ * the properties. Some domains require the properties to be set before they
+ * can be enabled.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
+roctracer_status_t roctracer_set_properties(roctracer_domain_t domain,
+                                            void* properties);
 
-// Runtime API callback type
+/** @} */
+
+/** \defgroup callback_api_group Callback API
+ *
+ * ROC tracer provides support for runtime API callbacks and activity
+ * records logging. The API callbacks provide the API calls arguments and are
+ * called on different phases, on enter, on exit, on kernel completion.
+ *
+ * @{
+ */
+
+/**
+ * Runtime API callback type.
+ *
+ * The callback that will be invoked when an enabled runtime API is called. The
+ * callback is invoked on entry and on exit.
+ */
 typedef activity_rtapi_callback_t roctracer_rtapi_callback_t;
 
-// Enable runtime API callbacks
+/**
+ * Enable runtime API callback for a specific operation of a domain.
+ *
+ * @param domain The domain.
+ *
+ * @param op The operation ID in \p domain.
+ *
+ * @param callback The callback to invoke each time the operation is performed
+ * on entry and exit.
+ *
+ * @param arg Value to pass as last argument of \p callback.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_DOMAIN \p domain is invalid.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_PARAMETER \p op is invalid.
+ */
 roctracer_status_t roctracer_enable_op_callback(
-    activity_domain_t domain,            // tracing domain
-    uint32_t op,                         // API call ID
-    activity_rtapi_callback_t callback,  // callback function pointer
-    void* arg);                          // [in/out] callback arg
-roctracer_status_t roctracer_enable_domain_callback(
-    activity_domain_t domain,            // tracing domain
-    activity_rtapi_callback_t callback,  // callback function pointer
-    void* arg);                          // [in/out] callback arg
-roctracer_status_t roctracer_enable_callback(
-    activity_rtapi_callback_t callback,  // callback function pointer
-    void* arg);                          // [in/out] callback arg
+    activity_domain_t domain,
+    uint32_t op,
+    activity_rtapi_callback_t callback,
+    void* arg);
 
-// Disable runtime API callbacks
-roctracer_status_t roctracer_disable_op_callback(activity_domain_t domain,       // tracing domain
-                                                 uint32_t op);                   // API call ID
-roctracer_status_t roctracer_disable_domain_callback(activity_domain_t domain);  // tracing domain
+/**
+ * Enable runtime API callback for all operations of a domain.
+ *
+ * @param domain The domain
+ *
+ * @param callback The callback to invoke each time the operation is performed
+ * on entry and exit.
+ *
+ * @param arg Value to pass as last argument of \p callback.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_DOMAIN \p domain is invalid.
+ */
+roctracer_status_t roctracer_enable_domain_callback(
+    activity_domain_t domain,
+    activity_rtapi_callback_t callback,
+    void* arg);
+
+/**
+ * Enable runtime API callback for all operations of all domains.
+ *
+ * @param callback The callback to invoke each time the operation is performed
+ * on entry and exit.
+ *
+ * @param arg Value to pass as last argument of \p callback.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
+roctracer_status_t roctracer_enable_callback(
+    activity_rtapi_callback_t callback,
+    void* arg);
+
+/**
+ * Disable runtime API callback for a specific operation of a domain.
+ *
+ * @param domain The domain
+ *
+ * @param op The operation in \p domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_DOMAIN \p domain is invalid.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_PARAMETER \p op is invalid.
+ */
+roctracer_status_t roctracer_disable_op_callback(activity_domain_t domain,
+                                                 uint32_t op);
+
+/**
+ * Disable runtime API callback for all operations of a domain.
+ *
+ * @param domain The domain
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ::ROCTRACER_STATUS_BAD_DOMAIN \p domain is invalid.
+ */
+roctracer_status_t roctracer_disable_domain_callback(activity_domain_t domain);
+
+/**
+ * Disable runtime API callback for all operations of all domains.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_disable_callback();
 
-////////////////////////////////////////////////////////////////////////////////
-// Activity API
-//
-// The activity records are asynchronously logged to the pool and can be associated
-// with the respective API callbacks using the correlation ID. Activity API can
-// be used to enable collecting of the records with timestamping data for API
-// calls and the kernel submits.
-// Methods return non zero on error and library errno is set.
+/** @} */
 
-// Activity record type
+/** \defgroup activity_api_group Activity API
+ *
+ * The activity records are asynchronously logged to the pool and can be associated
+ * with the respective API callbacks using the correlation ID. Activity API can
+ * be used to enable collecting of the records with timestamping data for API
+ * calls and the kernel submits.
+ *
+ * @{
+ */
+
+/**
+ * Activity record.
+ *
+ * Asynchronous activity events generate activity records.
+ */
 typedef activity_record_t roctracer_record_t;
 
+/**
+ * Get a pointer to the next activity record.
+ *
+ * A memory pool generates buffers that contain multiple activity records.
+ * This function steps to the next activity record.
+ *
+ * @param[in] record Pointer to ac activity record in a memory pool buffer.
+ *
+ * @param[out] next Pointer to the following activity record in the memory pool
+ * buffer.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 // Return next record
 static inline roctracer_status_t roctracer_next_record(
     const activity_record_t* record,  // [in] record ptr
@@ -144,105 +385,356 @@ static inline roctracer_status_t roctracer_next_record(
   return ROCTRACER_STATUS_SUCCESS;
 }
 
-// Tracer allocator type
-typedef void (*roctracer_allocator_t)(char** ptr,   // memory pointer
-                                      size_t size,  // memory size
-                                      void* arg);   // allocator arg
+/**
+ * Memory pool allocator callback.
+ *
+ * \p ptr is the allocated memory when \p size is greater than 0 and the
+ * address of the memory to deallocate when \p size is o.
+ *
+ * \p size is the size of the allocation request in bytes if greater than 0.
+ * If 0 requests deallocation.
+ *
+ * \p arg Argument provided when the callback is defined.
+ */
+typedef void (*roctracer_allocator_t)(char** ptr,
+                                      size_t size,
+                                      void* arg);
 
-// Pool callback type
+/**
+ * Memory pool buffer callback.
+ *
+ * The callback that will be invoked when a memory pool buffer becomes full or
+ * is flushed.
+ *
+ * \p begin pointer to first entry entry in the buffer.
+ *
+ * \p end pointer to one past the end entry in the buffer.
+ *
+ * \p arg the argument specified when the callback was defined.
+ */
 typedef void (*roctracer_buffer_callback_t)(
     const char* begin,  // [in] available buffered trace records
     const char* end,    // [in] end of buffered trace records
     void* arg);         // [in/out] callback arg
 
-// Tracer properties
+/**
+ * Memory pool properties.
+ *
+ * Defines the propertis when a tracer memory pool is created.
+ */
 typedef struct {
-  uint32_t mode;                                    // roctracer mode
-  size_t buffer_size;                               // buffer size
-  roctracer_allocator_t alloc_fun;                  // memory allocator function pointer
-  void* alloc_arg;                                  // memory allocator function pointer
-  roctracer_buffer_callback_t buffer_callback_fun;  // tracer record callback function
-  void* buffer_callback_arg;                        // tracer record callback arg
+
+  /**
+   * ROC Tracer mode.
+   */
+  uint32_t mode;
+
+  /**
+   * Size of buffer in bytes.
+   */
+  size_t buffer_size;
+
+  /**
+   * The allocator function to use to allocate and deallocate the buffer. If
+   * NULL then \p malloc and \p free are used.
+   */
+  roctracer_allocator_t alloc_fun;
+
+  /**
+   * The argument to pass when invoking the \p alloc_fun allocator.
+   */
+  void* alloc_arg;
+
+  /**
+   * The function to call when a buffer becomes full or is flushed.
+   */
+  roctracer_buffer_callback_t buffer_callback_fun;
+
+  /**
+   * The argument to pass when invoking the \p buffer_callback_fun callback.
+   */
+  void* buffer_callback_arg;
 } roctracer_properties_t;
 
-// Tracer memory pool type
+/**
+ * Tracer memory pool type.
+ */
 typedef void roctracer_pool_t;
 
-// Create tracer memory pool
-// The first invocation sets the default pool
+/**
+ * Create tracer memory pool.
+ *
+ * If \p pool is not NULL, returns the created memory pool.
+ *
+ * If \p pool is NULL sets the default memory pool to the created pool if not
+ * already defined. Otherwise, return an error.
+ *
+ * @param[in] properties Tracer memory pool properties.
+ *
+ * @param[out] pool Tracer memory pool created if not NULL.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ROCTRACER_STATUS_ERROR \p pool is NULL and the default pool is
+ * already defined. Unable to create the pool.
+ */
 roctracer_status_t roctracer_open_pool_expl(
-    const roctracer_properties_t* properties,  // tracer pool properties
-    roctracer_pool_t** pool);                  // [out] returns tracer pool if not NULL,
-                               // otherwise sets the default one if it is not set yet
+    const roctracer_properties_t* properties,
+    roctracer_pool_t** pool);
+
+/**
+ * Create tracer memory pool.
+ *
+ * Sets the default memory pool to the created pool if not already defined.
+ * Otherwise, return an error.
+ *
+ * @param[in] properties Tracer memory pool properties.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ *
+ * @retval ROCTRACER_STATUS_ERROR The default pool is already defined. Unable
+ * to create the pool.
+ */
 static inline roctracer_status_t roctracer_open_pool(
-    const roctracer_properties_t* properties)  // tracer pool properties
+    const roctracer_properties_t* properties)
 {
   return roctracer_open_pool_expl(properties, NULL);
 }
-// otherwise the error is generated
 
-// Close tracer memory pool
+/**
+ * Close tracer memory pool.
+ *
+ * @param[in] pool Memory pool to close. If NULL, the default memory pool is closed and set to undefined.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_close_pool_expl(
-    roctracer_pool_t* pool);  // [in] memory pool, NULL is a default one
+    roctracer_pool_t* pool);
+
+/**
+ * Close default tracer memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 static inline roctracer_status_t roctracer_close_pool() { return roctracer_close_pool_expl(NULL); }
 
+/**
+ * Query and set the default memory pool.
+ *
+ * @param[in] pool If not NULL, change the current default pool to \p pool.
+ *
+ * @return Return the current default memory pool before any change.
+ */
 // Return current default pool
 // Set new default pool if the argument is not NULL
 roctracer_pool_t* roctracer_default_pool_expl(
     roctracer_pool_t* pool);  // [in] new default pool if not NULL
+
+/**
+ * Query current default memory pool.
+ *
+ * @return Return the current default memory pool.
+ */
 static inline roctracer_pool_t* roctracer_default_pool() {
   return roctracer_default_pool_expl(NULL);
 }
 
-// Enable activity records logging
+/**
+ * Enable activity record logging for a specified operation of a domain
+ * providing a memory pool.
+ *
+ * @param[in] domain The domain.
+ *
+ * @param[in] op The activity operation ID in \p domain.
+ *
+ * @param[in] pool The memory pool to write the activity record. If NULL, use the
+ * default memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_enable_op_activity_expl(
-    activity_domain_t domain,  // tracing domain
-    uint32_t op,               // activity op ID
-    roctracer_pool_t* pool);   // memory pool, NULL is a default one
+    activity_domain_t domain,
+    uint32_t op,
+    roctracer_pool_t* pool);
+
+/**
+ * Enable activity record logging for a specified operation of a domain using
+ * the default memory pool.
+ *
+ * @param[in] domain The domain.
+ *
+ * @param[in] op The activity operation ID in \p domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 static inline roctracer_status_t roctracer_enable_op_activity(
-    activity_domain_t domain,  // tracing domain
-    uint32_t op)               // activity op ID
+    activity_domain_t domain,
+    uint32_t op)
 {
   return roctracer_enable_op_activity_expl(domain, op, NULL);
 }
+
+/**
+ * Enable activity record logging for all operations of a domain providing a
+ * memory pool.
+ *
+ * @param[in] domain The domain.
+ *
+ * @param[in] pool The memory pool to write the activity record. If NULL, use the
+ * default memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_enable_domain_activity_expl(
     activity_domain_t domain,  // tracing domain
     roctracer_pool_t* pool);   // memory pool, NULL is a default one
+
+/**
+ * Enable activity record logging for all operations of a domain using the
+ * default memory pool.
+ *
+ * @param[in] domain The domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 static inline roctracer_status_t roctracer_enable_domain_activity(
-    activity_domain_t domain)  // tracing domain
+    activity_domain_t domain)
 {
   return roctracer_enable_domain_activity_expl(domain, NULL);
 }
+
+/**
+ * Enable activity record logging for all operations of all domains providing a
+ * memory pool.
+ *
+ * @param[in] pool The memory pool to write the activity record. If NULL, use the
+ * default memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_enable_activity_expl(
-    roctracer_pool_t* pool);  // memory pool, NULL is a default one
+    roctracer_pool_t* pool);
+
+/**
+ * Enable activity record logging for all operations of all domains using the
+ * default memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 static inline roctracer_status_t roctracer_enable_activity() {
   return roctracer_enable_activity_expl(NULL);
 }
 
-// Disable activity records logging
-roctracer_status_t roctracer_disable_op_activity(activity_domain_t domain,       // tracing domain
-                                                 uint32_t op);                   // activity op ID
-roctracer_status_t roctracer_disable_domain_activity(activity_domain_t domain);  // tracing domain
+/**
+ * Disable activity record logging for a specified operation of a domain.
+ *
+ * @param[in] domain The domain.
+ *
+ * @param[in] op The activity operation ID in \p domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
+//
+roctracer_status_t roctracer_disable_op_activity(activity_domain_t domain,
+                                                 uint32_t op);
+
+/**
+ * Disable activity record logging for all operations of a domain.
+ *
+ * @param[in] domain The domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
+roctracer_status_t roctracer_disable_domain_activity(activity_domain_t domain);
+
+/**
+ * Disable activity record logging for all operations of all domains.
+ *
+ * @param[in] op The activity operation ID in \p domain.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_disable_activity();
 
-// Flush available activity records
+/**
+ * Flush available activity records for a memory pool.
+ *
+ * @param[in] pool The memory pool to flush. If NULL, flushes the default memory
+ * pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 roctracer_status_t roctracer_flush_activity_expl(
-    roctracer_pool_t* pool);  // memory pool, NULL is a default one
+    roctracer_pool_t* pool);
+
+/**
+ * Flush available activity records for the default memory pool.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
 static inline roctracer_status_t roctracer_flush_activity() {
   return roctracer_flush_activity_expl(NULL);
 }
 
-// Get system timestamp
-roctracer_status_t roctracer_get_timestamp(uint64_t* timestamp);  // [out] return timestamp
+/** @} */
 
-// Load/Unload methods
+/** \defgroup timestamp_group Timestamp Operations
+ *
+ *
+ *
+ * @{
+ */
+
+/**
+ * Get the system clock timestamp.
+ *
+ * @param[out] timestamp The system clock timestamp in nano seconds.
+ *
+ * @retval ::ROCTRACER_STATUS_SUCCESS The function has been executed
+ * successfully.
+ */
+roctracer_status_t roctracer_get_timestamp(uint64_t* timestamp);
+
+/** @} */
+
+/** \defgroup internal_group Internal Operations
+ *
+ * \todo Should these operation be part of the API?
+ *
+ * @{
+ */
+
+/**
+ * Load ROC Tracer library.
+ */
 bool roctracer_load();
+
+/**
+ * Unload ROC Tracer library.
+ */
 void roctracer_unload();
+
+/**
+ * Flush trace buffers.
+ */
 void roctracer_flush_buf();
 
-// Set properties
-roctracer_status_t roctracer_set_properties(roctracer_domain_t domain,  // tracing domain
-                                            void* properties);          // tracing properties
+/** @} */
 
 #ifdef __cplusplus
 }  // extern "C" block