Doxygen Improvements (#170)

* Doxygen updates

- Fix multiple @param where [in]/[out] was misplaced
- Fix @return
- Insert @retval
- Separate out installing conda environment from build docs step

[ROCm/rocprofiler-sdk commit: 14373c57be]

projects/rocprofiler-sdk/.github/workflows/docs.yml

@@ -47,10 +47,13 @@ jobs:
       - name: Create Docs Directory
         run:
           mkdir -p docs
-      - name: Update Docs
+      - name: Install Conda environment
         working-directory: source/docs
         run: |
           conda env create -n rocprofiler-docs -f environment.yml
+      - name: Build Docs
+        working-directory: source/docs
+        run: |
           source activate
           conda activate rocprofiler-docs
           ../scripts/update-docs.sh

projects/rocprofiler-sdk/source/include/rocprofiler/buffer_tracing.h

@@ -242,15 +242,16 @@ rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t
  * string literal that is encoded in the read-only section of the binary (i.e. it is always
  * "allocated" and never "deallocated").
  *
- * @param kind [in] Buffer tracing domain
- * @param name [out] If non-null and the name is a constant string that does not require dynamic
+ * @param [in] kind Buffer tracing domain
+ * @param [out] name If non-null and the name is a constant string that does not require dynamic
  * allocation, this paramter will be set to the address of the string literal, otherwise it will
  * be set to nullptr
- * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of
+ * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of
  * the name is a constant string or requires dynamic allocation)
- * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND if the
- * domain id is not valid. Returns @ref ROCPROFILER_STATUS_SUCCESS for a valid domain regardless if
- * there is a constant string or not.
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Returned if the domain id is not valid
+ * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if a valid domain, regardless if there is a
+ * constant string or not.
  */
 rocprofiler_status_t
 rocprofiler_query_buffer_tracing_kind_name(rocprofiler_service_buffer_tracing_kind_t kind,
@@ -262,18 +263,20 @@ rocprofiler_query_buffer_tracing_kind_name(rocprofiler_service_buffer_tracing_ki
  * string literal that is encoded in the read-only section of the binary (i.e. it is always
  * "allocated" and never "deallocated").
  *
- * @param kind [in] Buffer tracing domain
- * @param operation [in] Enumeration id value which maps to a specific API function or event type
- * @param name [out] If non-null and the name is a constant string that does not require dynamic
+ * @param [in] kind Buffer tracing domain
+ * @param [in] operation Enumeration id value which maps to a specific API function or event type
+ * @param [out] name If non-null and the name is a constant string that does not require dynamic
  * allocation, this paramter will be set to the address of the string literal, otherwise it will
  * be set to nullptr
- * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of
+ * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of
  * the name is a constant string or requires dynamic allocation)
- * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND on an invalid
- * domain id. Returns @ref ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND if the operation number is
- * not recognized for the given domain. Returns @ref ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if
- * rocprofiler does not support providing the operation name within this domain. Returns @ref
- * ROCPROFILER_STATUS_SUCCESS for valid domain and operation regardless of whether there is a
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND An invalid domain id
+ * @retval ::ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND The operation number is not recognized for
+ * the given domain
+ * @retval ::ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED Rocprofiler does not support providing the
+ * operation name within this domain
+ * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain and operation, regardless of whether there is a
  * constant string or not.
  */
 rocprofiler_status_t

projects/rocprofiler-sdk/source/include/rocprofiler/callback_tracing.h

@@ -183,10 +183,10 @@ typedef struct
  * new external correlation ids in the enter phase, it is recommended to pop the external
  * correlation id in the exit callback.
  *
- * @param record [in] Callback record data
- * @param user_data [in,out] This paramter can be used to retain information in between the enter
+ * @param [in] record Callback record data
+ * @param [in,out] user_data This paramter can be used to retain information in between the enter
  * and exit phases.
- * @param callback_data [in] User data provided when configuring the callback tracing service
+ * @param [in] callback_data User data provided when configuring the callback tracing service
  */
 typedef void (*rocprofiler_callback_tracing_cb_t)(rocprofiler_callback_tracing_record_t record,
                                                   rocprofiler_user_data_t*              user_data,
@@ -215,13 +215,13 @@ typedef int (*rocprofiler_callback_tracing_kind_operation_cb_t)(
  * This function will be invoked for each argument.
  * @see rocprofiler_iterate_callback_tracing_operation_args
  *
- * @param kind [in] domain
- * @param operation [in] associated domain operation
- * @param arg_number [in] the argument number, starting at zero
- * @param arg_name [in] the name of the argument in the prototype (or rocprofiler union)
- * @param arg_value_str [in] conversion of the argument to a string, e.g. operator<< overload
- * @param arg_value_addr [in] the address of the argument stored by rocprofiler.
- * @param data [in] user data
+ * @param [in] kind domain
+ * @param [in] operation associated domain operation
+ * @param [in] arg_number the argument number, starting at zero
+ * @param [in] arg_name the name of the argument in the prototype (or rocprofiler union)
+ * @param [in] arg_value_str conversion of the argument to a string, e.g. operator<< overload
+ * @param [in] arg_value_addr the address of the argument stored by rocprofiler.
+ * @param [in] data user data
  */
 typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)(
     rocprofiler_service_callback_tracing_kind_t kind,
@@ -251,11 +251,12 @@ typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)(
  * array.
  * @param [in] callback The function to invoke before and after an API function
  * @param [in] callback_args Data provided to every invocation of the callback function
- * @return ::rocprofiler_status_t Will return @ref ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED if
- * invoked outside of the initialization function in @ref rocprofiler_tool_configure_result_t
- * provided to rocprofiler via @ref rocprofiler_configure function. Will return @ref
- * ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the provided context is not valid/registered. Will
- * return @ref ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED if the same @ref
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Invoked outside of the initialization
+ * function in @ref rocprofiler_tool_configure_result_t provided to rocprofiler via @ref
+ * rocprofiler_configure function
+ * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND The provided context is not valid/registered
+ * @retval ::ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED if the same @ref
  * rocprofiler_service_callback_tracing_kind_t value is provided more than once (per context) -- in
  * other words, we do not support overriding or combining the operations in separate function calls.
  *
@@ -273,13 +274,13 @@ rocprofiler_configure_callback_tracing_service(rocprofiler_context_id_t context_
  * string literal that is encoded in the read-only section of the binary (i.e. it is always
  * "allocated" and never "deallocated").
  *
- * @param kind [in] Callback tracing domain
- * @param name [out] If non-null and the name is a constant string that does not require dynamic
+ * @param [in] kind Callback tracing domain
+ * @param [out] name If non-null and the name is a constant string that does not require dynamic
  * allocation, this paramter will be set to the address of the string literal, otherwise it will
  * be set to nullptr
- * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of
+ * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of
  * the name is a constant string or requires dynamic allocation)
- * @return rocprofiler_status_t
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t
 rocprofiler_query_callback_tracing_kind_name(rocprofiler_service_callback_tracing_kind_t kind,
@@ -291,16 +292,17 @@ rocprofiler_query_callback_tracing_kind_name(rocprofiler_service_callback_tracin
  * string literal that is encoded in the read-only section of the binary (i.e. it is always
  * "allocated" and never "deallocated").
  *
- * @param kind [in] Callback tracing domain
- * @param operation [in] Enumeration id value which maps to a specific API function or event type
- * @param name [out] If non-null and the name is a constant string that does not require dynamic
+ * @param [in] kind Callback tracing domain
+ * @param [in] operation Enumeration id value which maps to a specific API function or event type
+ * @param [out] name If non-null and the name is a constant string that does not require dynamic
  * allocation, this paramter will be set to the address of the string literal, otherwise it will
  * be set to nullptr
- * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of
+ * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of
  * the name is a constant string or requires dynamic allocation)
- * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND if the
- * domain id is not valid. Returns @ref ROCPROFILER_STATUS_SUCCESS for a valid domain regardless if
- * there is a constant string or not.
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Domain id is not valid
+ * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain provided, regardless if there is a constant
+ * string or not.
  */
 rocprofiler_status_t
 rocprofiler_query_callback_tracing_kind_operation_name(
@@ -310,20 +312,13 @@ rocprofiler_query_callback_tracing_kind_operation_name(
     uint64_t*                                   name_len) ROCPROFILER_API;
 
 /**
- * @brief Iterate over all the mappings of the callback tracing kinds and get a callback with the id
- * mapped to a constant string. The strings provided in the arg will be valid pointers for the
- * entire duration of the program. It is recommended to call this function once and cache this data
- * in the client instead of making multiple on-demand calls.
+ * @brief Iterate over all the mappings of the callback tracing kinds and get a callback for each
+ * kind.
  *
  * @param [in] callback Callback function invoked for each enumeration value in @ref
  * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values.
  * @param [in] data User data passed back into the callback
- * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND on an invalid
- * domain id. Returns @ref ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND if the operation number is
- * not recognized for the given domain. Returns @ref ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if
- * rocprofiler does not support providing the operation name within this domain. Returns @ref
- * ROCPROFILER_STATUS_SUCCESS for valid domain and operation regardless of whether there is a
- * constant string or not.
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_iterate_callback_tracing_kinds(rocprofiler_callback_tracing_kind_cb_t callback,
@@ -331,15 +326,16 @@ rocprofiler_iterate_callback_tracing_kinds(rocprofiler_callback_tracing_kind_cb_
 
 /**
  * @brief Iterates over all the mappings of the operations for a given @ref
- * rocprofiler_service_callback_tracing_kind_t and invokes the callback with the kind, operation id,
- * and the string mapping to the operation id. The strings provided in the callback arg will be
- * valid pointers for the entire duration of the program. It is recommended to call this function
- * once per kind, and cache this data in the client instead of making multiple on-demand calls.
+ * rocprofiler_service_callback_tracing_kind_t and invokes the callback with the kind id, operation
+ * id, and user-provided data.
  *
  * @param [in] kind which tracing callback kind operations to iterate over
  * @param [in] callback Callback function invoked for each operation associated with @ref
  * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values.
  * @param [in] data User data passed back into the callback
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Invalid domain id
+ * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_iterate_callback_tracing_kind_operations(

projects/rocprofiler-sdk/source/include/rocprofiler/context.h

@@ -43,7 +43,7 @@ ROCPROFILER_EXTERN_C_INIT
 /**
  * @brief Create context.
  *
- * @param context_id [out] Context identifier
+ * @param [out] context_id Context identifier
  * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t ROCPROFILER_API

projects/rocprofiler-sdk/source/include/rocprofiler/counters.h

@@ -52,7 +52,7 @@ rocprofiler_query_counter_name(rocprofiler_counter_id_t counter_id, const char**
  * @param [in] agent rocprofiler agent
  * @param [in] counter_id counter id (obtained from iterate_agent_supported_counters)
  * @param [out] instance_count number of instances the counter has
- * @return rocprofiler_status_t
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_counter_instance_count(rocprofiler_agent_t      agent,

projects/rocprofiler-sdk/source/include/rocprofiler/external_correlation.h

@@ -34,17 +34,16 @@ ROCPROFILER_EXTERN_C_INIT
  * @{
  */
 
-/** @} */
-
 /**
  * @brief Push default value for `external` field in @ref rocprofiler_correlation_id_t onto stack.
  *
- * @param context [in] Associated context
- * @param tid [in] thread identifier. @see rocprofiler_get_thread_id
- * @param external_correlation_id [in] User data to place in external field in @ref
+ * @param [in] context Associated context
+ * @param [in] tid thread identifier. @see rocprofiler_get_thread_id
+ * @param [in] external_correlation_id User data to place in external field in @ref
  * rocprofiler_correlation_id_t
- * @return rocprofiler_status_t Returns ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the context
- * does not exist. Returns ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT if thread id is not valid.
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist
+ * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_push_external_correlation_id(rocprofiler_context_id_t context,
@@ -54,15 +53,18 @@ rocprofiler_push_external_correlation_id(rocprofiler_context_id_t context,
 /**
  * @brief Pop default value for `external` field in @ref rocprofiler_correlation_id_t off of stack
  *
- * @param context [in] Associated context
- * @param tid [in] thread identifier. @see rocprofiler_get_thread_id
- * @param external_correlation_id [out] Correlation id data popped off the stack
- * @return rocprofiler_status_t Returns ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the context
- * does not exist. Returns ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT if thread id is not valid.
+ * @param [in] context Associated context
+ * @param [in] tid thread identifier. @see rocprofiler_get_thread_id
+ * @param [out] external_correlation_id Correlation id data popped off the stack
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist
+ * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_pop_external_correlation_id(rocprofiler_context_id_t context,
                                         rocprofiler_thread_id_t  tid,
                                         rocprofiler_user_data_t* external_correlation_id);
 
+/** @} */
+
 ROCPROFILER_EXTERN_C_FINI

projects/rocprofiler-sdk/source/include/rocprofiler/fwd.h

@@ -388,8 +388,8 @@ typedef struct
  * @brief Function for computing the unsigned 64-bit hash value in @ref rocprofiler_record_header_t
  * from a category and kind (two unsigned 32-bit values)
  *
- * @param category [in] a value from @ref rocprofiler_buffer_category_t
- * @param kind [in] depending on the category, this is the domain value, e.g., @ref
+ * @param [in] category a value from @ref rocprofiler_buffer_category_t
+ * @param [in] kind depending on the category, this is the domain value, e.g., @ref
  * rocprofiler_service_buffer_tracing_kind_t value
  * @return uint64_t hash value of category and kind
  */

projects/rocprofiler-sdk/source/include/rocprofiler/internal_threading.h

@@ -71,12 +71,12 @@ typedef void (*rocprofiler_internal_thread_library_cb_t)(rocprofiler_internal_th
  * caller is responsible for ignoring these callbacks if they want to ignore them beyond a certain
  * point in the application.
  *
- * @param precreate [in] Callback invoked immediately before a new internal thread is created
- * @param postcreate [in] Callback invoked immediately after a new internal thread is created
- * @param libs [in] Bitwise-or of libraries, e.g. `ROCPROFILER_LIBRARY | ROCPROFILER_MARKER_LIBRARY`
+ * @param [in] precreate Callback invoked immediately before a new internal thread is created
+ * @param [in] postcreate Callback invoked immediately after a new internal thread is created
+ * @param [in] libs Bitwise-or of libraries, e.g. `ROCPROFILER_LIBRARY | ROCPROFILER_MARKER_LIBRARY`
  * means the callbacks will be invoked whenever rocprofiler and/or the marker library create
  * internal threads but not when the HSA or HIP libraries create internal threads.
- * @param data [in] Data shared between callbacks
+ * @param [in] data Data shared between callbacks
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_at_internal_thread_create(rocprofiler_internal_thread_library_cb_t precreate,

projects/rocprofiler-sdk/source/include/rocprofiler/registration.h

@@ -74,7 +74,7 @@ typedef struct
  *
  * @param [out] status 0 indicates rocprofiler has not been initialized (i.e. configured), 1
  * indicates rocprofiler has been initialized, -1 indicates rocprofiler is currently initializing.
- * @return rocprofiler_status_t
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t
 rocprofiler_is_initialized(int* status) ROCPROFILER_API;
@@ -84,7 +84,7 @@ rocprofiler_is_initialized(int* status) ROCPROFILER_API;
  *
  * @param [out] status 0 indicates rocprofiler has not been finalized, 1 indicates rocprofiler has
  * been finalized, -1 indicates rocprofiler is currently finalizing.
- * @return rocprofiler_status_t
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t
 rocprofiler_is_finalized(int* status) ROCPROFILER_API;

projects/rocprofiler-sdk/source/lib/rocprofiler/counters.cpp

@@ -37,7 +37,7 @@ rocprofiler_query_counter_name(rocprofiler_counter_id_t counter_id, const char**
  *
  * @param [in] counter_id
  * @param [out] instance_count
- * @return rocprofiler_status_t
+ * @return ::rocprofiler_status_t
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_counter_instance_count(rocprofiler_agent_t      agent,