Documentation Update For Counters (#246)

* Documentation Update

* Minor fixes

* source formatting (clang-format v11) (#265)

Co-authored-by: bwelton <bwelton@users.noreply.github.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: bwelton <bwelton@users.noreply.github.com>

source/include/rocprofiler-sdk/counters.h

@@ -35,25 +35,27 @@ ROCPROFILER_EXTERN_C_INIT
  */
 
 /**
- * @brief Query counter id information from record_id
+ * @brief Query counter id information from record_id.
  *
  * @param [in] id record id from rocprofiler_record_counter_t
  * @param [out] counter_id counter id associated with the record
  * @return ::rocprofiler_status_t
+ * @retval ROCPROFILER_STATUS_SUCCESS if id decoded
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_record_counter_id(rocprofiler_counter_instance_id_t id,
                                     rocprofiler_counter_id_t* counter_id) ROCPROFILER_NONNULL(2);
 
 /**
- * @brief Query dimension position from record_id
+ * @brief Query dimension position from record_id. If the dimension does not exist
+ *        in the counter, the return will be 0.
  *
- * @param [in] id record id from rocprofiler_record_counter_t
- * @param [in]  dim dimension for which positional info is requested
- * @param [out] pos value of the dimension in id.
+ * @param [in] id record id from @ref rocprofiler_record_counter_t
+ * @param [in]  dim dimension for which positional info is requested (currently only
+ *              0 is allowed, i.e. flat array without dimension).
+ * @param [out] pos value of the dimension in id
  * @return ::rocprofiler_status_t
- *
- * TODO(aelwazir): rocprofiler_status_t types that can be returned
+ * @retval ROCPROFILER_STATUS_SUCCESS if dimension decoded
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_record_dimension_position(rocprofiler_counter_instance_id_t  id,
@@ -61,15 +63,16 @@ rocprofiler_query_record_dimension_position(rocprofiler_counter_instance_id_t  i
                                             size_t* pos) ROCPROFILER_NONNULL(3);
 
 /**
- * @brief Return information about the dimension for a specified counter
+ * @brief Return information about the dimension for a specified counter. This call
+ *        is primary for future use not related to this alpha since the only dimension
+ *        supported is 0 (flat array without dimension).
  *
  * @param [in] id counter id to query dimension info for.
- * @param [in]  dim dimension
+ * @param [in]  dim dimension (currently only 0 is allowed)
  * @param [out] info info on the dimension (name, instance_size)
  * @return ::rocprofiler_status_t
- *
- * TODO(aelwazir): rocprofiler_status_t types that can be returned
- *
+ * @retval ROCPROFILER_STATUS_SUCCESS if dimension exists
+ * @retval ROCPROFILER_STATUS_ERROR if the dimension does not
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_record_dimension_info(rocprofiler_counter_id_t             id,
@@ -78,16 +81,15 @@ rocprofiler_query_record_dimension_info(rocprofiler_counter_id_t             id,
     ROCPROFILER_NONNULL(3);
 
 /**
- * @brief Query Counter name as a literal string.
+ * @brief Query Counter name. Name is a pointer controlled by rocprofiler and
+ *        should not be free'd or modified.
  *
- * @param [in] counter_id @see rocprofiler_iterate_agent_supported_counters to get the available
- * counter IDs
+ * @param [in] counter_id counter for which to get its name.
  * @param [out] name returns a pointer to the name of the counter
  * @param [out] size returns the size of the name returned
  * @return ::rocprofiler_status_t
- *
- * TODO(aelwazir): rocprofiler_status_t types that can be returned
- *
+ * @retval ROCPROFILER_STATUS_SUCCESS if counter found
+ * @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if counter not found
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_counter_name(rocprofiler_counter_id_t counter_id, const char** name, size_t* size)
@@ -104,14 +106,25 @@ 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
+ * @retval ROCPROFILER_STATUS_SUCCESS if counter found
+ * @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if counter not found
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_query_counter_instance_count(rocprofiler_agent_t      agent,
                                          rocprofiler_counter_id_t counter_id,
                                          size_t* instance_count) ROCPROFILER_NONNULL(3);
 
-// TODO(aelwazir): Ben to add a brief
+/**
+ * @brief Callback that gives a list of counters available on an agent. The
+ *        counters variable is owned by rocprofiler and should not be free'd.
+ *
+ * @param [in] counters An array of counters that are avialable on the agent
+ *      @ref rocprofiler_iterate_agent_supported_counters was called on.
+ * @param [in] num_counters Number of counters contained in counters
+ * @param [in] user_data User data supplied by
+ *      @ref rocprofiler_iterate_agent_supported_counters
+ */
 typedef rocprofiler_status_t (*rocprofiler_available_counters_cb_t)(
     rocprofiler_counter_id_t* counters,
     size_t                    num_counters,
@@ -124,6 +137,8 @@ typedef rocprofiler_status_t (*rocprofiler_available_counters_cb_t)(
  * @param [in] cb callback to caller to get counters
  * @param [in] user_data data to pass into the callback
  * @return ::rocprofiler_status_t
+ * @retval ROCPROFILER_STATUS_SUCCESS if counters found for agent
+ * @retval ROCPROFILER_STATUS_ERROR if no counters found for agent
  */
 rocprofiler_status_t ROCPROFILER_API
 rocprofiler_iterate_agent_supported_counters(rocprofiler_agent_t                 agent,