Making ROCTx API doxygen generated document more readable (#385)

* Making ROCTx API doxygen generated document more readable * fixing build * Fix linking errors * Fixing header * Fixing Topics and Types * doxygen configuration fixes * Fixing build * Fix unnecessory doc parsing warnings * formatting and linting fixes * rebasing SDK modular PR * Fixing missing line * Fixing ROCtx documentation after merge * Removing flake changes * changed back WARN_IF_DOC_ERROR to Yes
2025-05-23 04:38:55 +05:30
@@ -60,8 +60,22 @@ subtrees:
              - file: _doxygen/rocprofiler-sdk/html/topics
              - file: _doxygen/rocprofiler-sdk/html/annotated
              - file: _doxygen/rocprofiler-sdk/html/files
-    - file: _doxygen/roctx/html/index
-      title: ROCTx API library
+    - file: api-reference/rocprofiler-sdk-roctx_api_reference
+      subtrees:
+      - entries:
+        - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules
+          subtrees:
+          - entries:
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/markers
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/ranges
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/profiler-control
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/naming-utilities
+        - file: api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files
+          subtrees:
+          - entries:
+            - file: api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files/global_roctx_basic_data_types
+            - file: _doxygen/roctx/html/topics
+            - file: _doxygen/roctx/html/files
  - caption: Conceptual
    entries:
    - file: conceptual/comparing-with-legacy-tools
@@ -0,0 +1,15 @@
+.. meta::
+  :description: The Global Data structures, topics and files reference page.
+
+.. _global_roctx_data_structures_topics_files_reference:
+
+*******************************************************************************
+Global Data structures, topics, files
+*******************************************************************************
+
+This ROCprofiler-SDK-ROCTx API topic covers:
+
+* :ref:`global_roctx_basic_data_types_reference`
+* :doc:`../../_doxygen/roctx/html/topics`
+* :doc:`../../_doxygen/roctx/html/files`
+
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The global basic data types reference page.
+
+.. _global_roctx_basic_data_types_reference:
+
+*******************************************************************************
+Global Basic Data Types
+*******************************************************************************
+
+.. doxygengroup:: BASIC_DATA_TYPES
+   :content-only:
+   :project: roctx
@@ -0,0 +1,17 @@
+.. meta::
+  :description: The ROCprofiler-SDK-ROCTx API modules reference page.
+  :keywords: AMD, ROCm, modules
+
+.. _roctx_modules_reference:
+
+*******************************************************************************
+Modules
+*******************************************************************************
+
+The ROCprofiler-SDK-ROCTx API is organized into the following modules based on functionality:
+
+* :ref:`markers_information_reference`
+* :ref:`ranges_information_reference`
+* :ref:`profiler-control_information_reference`
+* :ref:`naming-utilities_information_reference`
+
@@ -0,0 +1,12 @@
+.. meta::
+  :description: Markers Information reference page.
+
+.. _markers_information_reference:
+
+*******************************************************************************
+Markers Information
+*******************************************************************************
+
+.. doxygengroup:: marker_group
+   :content-only:
+   :project: roctx
@@ -0,0 +1,12 @@
+.. meta::
+  :description: Naming utilities Information reference page.
+
+.. _naming-utilities_information_reference:
+
+*******************************************************************************
+Naming Information
+*******************************************************************************
+
+.. doxygengroup:: UTILITIES
+   :content-only:
+   :project: roctx
@@ -0,0 +1,12 @@
+.. meta::
+  :description: Profiler Control Information reference page.
+
+.. _profiler-control_information_reference:
+
+*******************************************************************************
+Profiler Control Information
+*******************************************************************************
+
+.. doxygengroup:: PROFILER_COMM
+   :content-only:
+   :project: roctx
@@ -0,0 +1,12 @@
+.. meta::
+  :description: Ranges Information reference page.
+
+.. _ranges_information_reference:
+
+*******************************************************************************
+Ranges Information
+*******************************************************************************
+
+.. doxygengroup:: range_group
+   :content-only:
+   :project: roctx
@@ -0,0 +1,66 @@
+.. meta::
+  :description: ROCprofiler-SDK-ROCTx API reference page
+  :keywords: AMD, ROCm, HSA
+
+.. _rocprofiler_sdk_roctx_api_reference:
+
+********************************************************************************
+ROCTx API
+********************************************************************************
+
+Introduction
+============
+
+ROCTx is a comprehensive library that implements the AMD code annotation API. It provides
+essential functionality for:
+
+- Event annotation and marking
+- Code range tracking and management
+- Profiler control and customization
+- Thread and device naming capabilities
+
+Key features:
+
+- Nested range tracking with push/pop functionality
+- Process-wide range management
+- Thread-specific and global profiler control
+- Device and stream naming support
+- HSA agent and HIP device management
+
+The API is divided into several main components:
+
+1. **Markers** - For single event annotations
+2. **Ranges** - For tracking code execution spans
+3. **Profiler Control** - For managing profiling tool behavior
+4. **Naming Utilities** - For labeling threads, devices, and streams
+
+Thread Safety:
+
+- Range operations are thread-local and thread-safe
+- Marking operations are thread-safe
+- Profiler control operations are process-wide
+
+Integration:
+
+- Compatible with HIP runtime
+- Supports HSA (Heterogeneous System Architecture)
+- Provides both C and C++ interfaces
+
+Performance Considerations:
+
+- Minimal overhead for marking and range operations
+- Thread-local storage for efficient range stacking
+- Lightweight profiler control mechanisms
+
+.. note::
+
+   All string parameters must be null-terminated.
+
+.. warning::
+
+   Proper nesting of range push/pop operations is the user's responsibility.
+
+This ROCTx API topic broadly covers:
+
+* :ref:`roctx_modules_reference`
+* :ref:`global_roctx_data_structures_topics_files_reference`
@@ -8,4 +8,5 @@ Agent Information
 *******************************************************************************

 .. doxygengroup:: AGENTS
+   :project: rocprofiler-sdk
   :content-only:
@@ -9,3 +9,4 @@ Buffer handling

 .. doxygengroup:: BUFFER_HANDLING
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Buffer tracing

 .. doxygengroup:: BUFFER_TRACING_SERVICE
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Callback tracing

 .. doxygengroup:: CALLBACK_TRACING_SERVICE
   :content-only:
+   :project: rocprofiler-sdk   
@@ -9,3 +9,4 @@ Context management

 .. doxygengroup:: CONTEXT_OPERATIONS
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Counter config

 .. doxygengroup:: COUNTER_CONFIG
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Counters

 .. doxygengroup:: COUNTERS
   :content-only:
+   :project: rocprofiler-sdk   
@@ -9,3 +9,4 @@ Device counting service

 .. doxygengroup:: device_counting_service
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Dispatch counting service

 .. doxygengroup:: dispatch_counting_service
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ External correlation

 .. doxygengroup:: EXTERNAL_CORRELATION
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Intercept table

 .. doxygengroup:: INTERCEPT_TABLE
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Internal threading management

 .. doxygengroup:: INTERNAL_THREADING
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ OMPT Registration

 .. doxygengroup:: OMPT_REGISTRATION
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ PC Sampling service

 .. doxygengroup:: PC_SAMPLING_SERVICE
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Thread trace

 .. doxygengroup:: THREAD_TRACE
   :content-only:
+   :project: rocprofiler-sdk
@@ -9,3 +9,4 @@ Tool registration

 .. doxygengroup:: REGISTRATION_GROUP
   :content-only:
+   :project: rocprofiler-sdk
@@ -65,10 +65,13 @@ extensions = [

 doxygen_root = "."
 doxysphinx_enabled = True
-doxygen_project = {
-    "name": "rocprofiler-sdk",
-    "path": "_doxygen/rocprofiler-sdk/xml",
+
+breathe_projects = {
+    "rocprofiler-sdk": "_doxygen/rocprofiler-sdk/xml",
+    "roctx": "_doxygen/roctx/xml",
 }
+breathe_default_project = "rocprofiler-sdk"
+
 doxyfile = "rocprofiler-sdk.dox"

 external_projects_current_project = "rocprofiler-sdk"
@@ -81,6 +84,12 @@ external_toc_path = "./_toc.yml"
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 suppress_warnings = ["etoc.toctree"]
+nitpick_ignore = [
+    ("cpp:identifier", "uint32_t"),
+    ("cpp:identifier", "uint64_t"),
+    ("cpp:identifier", "hsa_agent_s"),
+    ("cpp:identifier", "ihipStream_t"),
+]

 # -- Options for HTML output -------------------------------------------------

@@ -44,7 +44,7 @@ The documentation is structured as follows:
    * :doc:`Counter collection services <api-reference/counter_collection_services>`
    * :doc:`PC sampling <api-reference/pc_sampling>`
    * :doc:`ROCprofiler-SDK API <api-reference/rocprofiler-sdk_api_reference>`
-    * :doc:`ROCTx API library <_doxygen/roctx/html/index>`
+    * :doc:`ROCTx API <api-reference/rocprofiler-sdk-roctx_api_reference>`

  .. grid-item-card:: Conceptual

@@ -152,18 +152,20 @@ EXCLUDE_PATTERNS       = */.git/* \
                         @SOURCE_DIR@/**/rocprofiler-sdk/**/* \
                         @SOURCE_DIR@/**/rocprofiler-sdk-roctx/api_trace.h
 EXCLUDE_SYMBOLS        = "std::*" \
-                         "ROCTX_ATTRIBUTE" \
+                         "ROCPROFILER_ATTRIBUTE" \
+                         "ROCPROFILER_API" \
+                         "ROCPROFILER_NONNULL" \
+                         "ROCPROFILER_PUBLIC_API" \
+                         "ROCPROFILER_HIDDEN_API" \
+                         "ROCPROFILER_EXPORT_DECORATOR" \
+                         "ROCPROFILER_IMPORT_DECORATOR" \
+                         "ROCPROFILER_EXPORT" \
+                         "ROCPROFILER_IMPORT" \
+                         "ROCPROFILER_HANDLE_LITERAL" \
+                         "ROCPROFILER_EXTERN_C_INIT" \
+                         "ROCPROFILER_EXTERN_C_FINI" \
                         "ROCTX_API" \
-                         "ROCTX_NONNULL" \
-                         "ROCTX_PUBLIC_API" \
-                         "ROCTX_HIDDEN_API" \
-                         "ROCTX_EXPORT_DECORATOR" \
-                         "ROCTX_IMPORT_DECORATOR" \
-                         "ROCTX_EXPORT" \
-                         "ROCTX_IMPORT" \
-                         "ROCTX_HANDLE_LITERAL" \
-                         "ROCTX_EXTERN_C_INIT" \
-                         "ROCTX_EXTERN_C_FINI"
+                         "ROCTX_NONNULL"
 EXAMPLE_PATH           = @SOURCE_DIR@/samples
 EXAMPLE_PATTERNS       = *.h \
                         *.hh \
@@ -169,7 +169,9 @@ EXCLUDE_SYMBOLS        = "std::*" \
                         "ROCPROFILER_EXTERN_C_FINI" \
                         "ROCPROFILER_SDK_DEPRECATED_WARNINGS" \
                         "ROCPROFILER_SDK_EXPERIMENTAL_WARNINGS" \
-                         "ROCPROFILER_*_LAST"
+                         "ROCPROFILER_*_LAST" \
+                         "ROCTX_API" \
+                         "ROCTX_NONNULL"
 EXAMPLE_PATH           = @SOURCE_DIR@/samples
 EXAMPLE_PATTERNS       = *.h \
                         *.hh \
@@ -32,7 +32,7 @@
 * dynamically loading the shared library with @p dlopen, the address of each
 * function can be obtained using @p dlsym with the name of the function and
 * its corresponding symbol version string.  An error will be reported by @p
- * dlvsym if the installed library does not support the version for the
+ * dlsym if the installed library does not support the version for the
 * function specified in this version of the interface.
 *
 * @{
@@ -79,7 +79,7 @@ ROCTX_EXTERN_C_INIT

 /** @defgroup marker_group ROCTx Markers
 *
- * Marker annotations are used to describe events in a ROCm application.
+ * @brief Markers are used to annotate specific events in the code execution.
 *
 * @{
 */
@@ -96,8 +96,14 @@ roctxMarkA(const char* message) ROCTX_API ROCTX_NONNULL(1);

 /** @defgroup range_group ROCTx Ranges
 *
- * Range annotations are used to describe events in a ROCm application.
+ * @brief Ranges are used to describe a span of code execution in a ROCm application.
 *
+ * Ranges can be nested, and the API provides functions to start and stop ranges.
+ * Ranges are thread-local, meaning that each thread can have its own stack of
+ * ranges. The API provides functions to push and pop ranges from the stack.
+ * The API also provides functions to start and stop ranges, which are
+ * process-wide. Each range is assigned a unique ID, which can be used to
+ * identify the range when stopping it.
 * @{
 */

@@ -152,7 +158,7 @@ roctxRangeStop(roctx_range_id_t id) ROCTX_API;

 /** @defgroup PROFILER_COMM ROCTx Application control/customization of profiling tools
 *
- * Applications can invoke these functions to control/customize profiling tool behavior.
+ * @brief Applications can invoke these functions to control/customize profiling tool behavior.
 *
 * @{
 */
@@ -192,6 +198,15 @@ roctxProfilerPause(roctx_thread_id_t tid) ROCTX_API;
 int
 roctxProfilerResume(roctx_thread_id_t tid) ROCTX_API;

+/** @} */
+
+/** \defgroup UTILITIES ROCTx Utility functions
+ *
+ * @brief Utility functions for profiling tools to customize their behavior.
+ *
+ * @{
+ */
+
 /**
 * @brief Indicate to a profiling tool that, where possible, you would like the current CPU OS
 * thread to be labeled by the provided name in the output of the profiling tool.
@@ -26,9 +26,9 @@

 #include <stdint.h>

-/** @defgroup DATA_TYPE ROCTx Data types
+/** \defgroup BASIC_DATA_TYPES ROCTx Data types
 *
- * Data types defined or aliased by ROCTx
+ *  @brief Data types defined or aliased by ROCTx
 *
 * @{
 */