Merge branch 'add_trace_doc_section' into 'master'

docs(esp_trace): restructure tracing docs with esp_trace as master

Closes DOC-13669

See merge request espressif/esp-idf!50215

components/esp_trace/README.md

@@ -473,5 +473,5 @@ For detailed usage instructions, see:
 Examples demonstrating trace usage can be found in:
 - `examples/system/app_trace_basic/` - Basic application tracing
 - `examples/system/sysview_tracing/` - SystemView tracing example
-- `examples/system/esp_trace/` - Minimal template for integrating an external trace library (encoder + FreeRTOS hooks + vtable lock)
+- `examples/system/esp_trace_custom_library/` - Minimal template for integrating an external trace library (encoder + FreeRTOS hooks + vtable lock)
 - `examples/system/sysview_tracing_heap_log/` - SystemView heap and log tracing example

components/esp_trace/include/esp_trace.h

@@ -5,6 +5,9 @@
  */
 #pragma once
 
+#include <stdbool.h>
+#include <stddef.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -36,9 +39,10 @@ typedef struct {
     /**
      * @brief Encoder name (required)
      *
-     * Must match a registered encoder name. Built-in encoders:
-     * - "sysview" - SEGGER SystemView protocol for FreeRTOS tracing
-     * - "raw" - Pass-through for raw binary data
+     * Must match the name of an encoder registered via ESP_TRACE_REGISTER_ENCODER().
+     * The esp_trace component ships no encoder itself; encoders are provided by
+     * external components (for example, espressif/esp_sysview registers a SystemView
+     * encoder).
      */
     const char *encoder_name;
 
@@ -55,6 +59,7 @@ typedef struct {
      *
      * Must match a registered transport name. Built-in transports:
      * - "apptrace" - Uses app_trace for JTAG or UART communication
+     * - "usb_serial_jtag" - Streams trace data over the USB Serial JTAG peripheral
      *
      */
     const char *transport_name;
@@ -142,7 +147,7 @@ esp_trace_link_types_t esp_trace_get_link_type(esp_trace_handle_t handle);
 /**
  * @brief Panic flush the trace handle. This function is called from panic handler.
  *
- * @param handle The trace handle
+ * @param info Panic info passed from the panic handler
  */
 void esp_trace_panic_handler(const void *info);
 

components/esp_trace/include/esp_trace_types.h

@@ -1,27 +1,38 @@
 /*
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
 
+#include <stdint.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @brief Core trace system configuration.
+ *
+ * Reserved for future core-level trace configuration.
+ */
 typedef struct esp_trace_config {
-    // Reserved for future use
-    int reserved;
+    int reserved;  ///< Reserved for future use.
 } esp_trace_config_t;
 
+/**
+ * @brief Trace transport link type.
+ */
 typedef enum {
-    ESP_TRACE_LINK_UNKNOWN = 0,
-    ESP_TRACE_LINK_DEBUG_PROBE,
-    ESP_TRACE_LINK_UART,
-    ESP_TRACE_LINK_USB_SERIAL_JTAG,
+    ESP_TRACE_LINK_UNKNOWN = 0,       ///< Unknown or unavailable link type.
+    ESP_TRACE_LINK_DEBUG_PROBE,       ///< Debug probe link, for example JTAG through OpenOCD.
+    ESP_TRACE_LINK_UART,              ///< UART link.
+    ESP_TRACE_LINK_USB_SERIAL_JTAG,   ///< USB Serial JTAG link.
 } esp_trace_link_types_t;
 
-/* Timeout constants for trace operations */
+/**
+ * @brief Infinite timeout for trace operations.
+ */
 #define ESP_TRACE_TMO_INFINITE          (UINT32_MAX)
 
 #ifdef __cplusplus