Merge branch 'bugfix/doxygen_input_file_bug' into 'master'

docs: fix doxygen compile warnings for doxygen 1.9.1

Closes IDFGH-4790 and DOC-993

See merge request espressif/esp-idf!13058

components/bt/host/bluedroid/api/include/api/esp_blufi_api.h

@@ -301,6 +301,7 @@ typedef void (* esp_blufi_event_cb_t)(esp_blufi_cb_event_t event, esp_blufi_cb_p
  * @param len  : length of data from phone
  * @param output_data : data want to send to phone
  * @param output_len : length of data want to send to phone
+ * @param need_free : output reporting if memory needs to be freed or not *
  */
 typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free);
 
@@ -311,7 +312,7 @@ typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8
  * @param crypt_len  : length of plain text
  * @return  Nonnegative number is encrypted length, if error, return negative number;
  */
-typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len);
+typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
 
 /**
  * @brief BLUFI  decrypt the data after negotiate a share key

components/bt/host/bluedroid/api/include/api/esp_gattc_api.h

@@ -259,7 +259,7 @@ typedef union {
 /**
  * @brief GATT Client callback function type
  * @param event : Event type
- * @param gatts_if : GATT client access interface, normally
+ * @param gattc_if : GATT client access interface, normally
  *                   different gattc_if correspond to different profile
  * @param param : Point to callback parameter, currently is union type
  */

components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h

@@ -188,7 +188,7 @@ typedef void (* esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len);
  *
  * @param[in]       len : size(in bytes) in buf
  *
- * @param[out]      length of data successfully read
+ * @return          length of data successfully read
  */
 typedef uint32_t (* esp_hf_outgoing_data_cb_t) (uint8_t *buf, uint32_t len);
 

components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h

@@ -273,7 +273,7 @@ typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t l
  *
  * @param[in]       len : size(in bytes) in buf
  *
- * @param[out]      length of data successfully read
+ * @return          length of data successfully read
  *
  */
 typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len);

docs/conf_common.py

@@ -359,7 +359,7 @@ html_static_path = ['../_static']
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ReadtheDocsTemplatedoc'
 
-google_analytics_id = os.environ['CI_GOOGLE_ANALYTICS_ID']
+google_analytics_id = os.environ.get('CI_GOOGLE_ANALYTICS_ID', None)
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/doxygen/Doxyfile_common

@@ -21,7 +21,6 @@ PROJECT_NAME = "IDF Programming Guide"
 ## and used to include in API reference documentation
 
 INPUT = \
-    ## TinyUSB
     $(IDF_PATH)/components/tinyusb/additions/include/tinyusb.h \
     $(IDF_PATH)/components/tinyusb/additions/include/tinyusb_types.h \
     $(IDF_PATH)/components/tinyusb/additions/include/tusb_cdc_acm.h \
@@ -29,47 +28,32 @@ INPUT = \
     $(IDF_PATH)/components/tinyusb/additions/include/tusb_console.h \
     $(IDF_PATH)/components/tinyusb/additions/include/tusb_tasks.h \
     $(IDF_PATH)/components/tinyusb/additions/include/vfs_tinyusb.h \
-    ##
-    ## Wi-Fi - API Reference
-    ##
     $(IDF_PATH)/components/esp_wifi/include/esp_wifi.h \
     $(IDF_PATH)/components/esp_wifi/include/esp_wifi_types.h \
     $(IDF_PATH)/components/esp_wifi/include/esp_smartconfig.h \
     $(IDF_PATH)/components/esp_wifi/include/esp_now.h \
     $(IDF_PATH)/components/esp_wifi/include/esp_wifi_default.h \
-    ## Mesh - API Reference
     $(IDF_PATH)/components/esp_wifi/include/esp_mesh.h \
-    ## Event loop - API Reference
     $(IDF_PATH)/components/esp_event/include/esp_event.h \
     $(IDF_PATH)/components/esp_event/include/esp_event_base.h \
     $(IDF_PATH)/components/esp_event/include/esp_event_legacy.h \
-    ## Bluetooth - API Reference
-    ## Controller && VHCI
     $(IDF_PATH)/components/bt/include/esp32/include/esp_bt.h \
-    ## Bluetooth COMMON
-    ## Issue with __attribute__
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
-    ## Bluetooth LE
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \
-    ## Issue with __attribute__
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \
-    ## Bluetooth Classic
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \
-    ## Issue with __attribute__
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
     $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \
-    ## NimBLE related Bluetooth APIs
     $(IDF_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
-    ## ESP BLE Mesh APIs
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \
@@ -83,17 +67,11 @@ INPUT = \
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \
     $(IDF_PATH)/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \
-    ##
-    ## Ethernet - API Reference
-    ##
     $(IDF_PATH)/components/esp_eth/include/esp_eth.h \
     $(IDF_PATH)/components/esp_eth/include/esp_eth_com.h \
     $(IDF_PATH)/components/esp_eth/include/esp_eth_mac.h \
     $(IDF_PATH)/components/esp_eth/include/esp_eth_phy.h \
     $(IDF_PATH)/components/esp_eth/include/esp_eth_netif_glue.h \
-    ##
-    ## Peripherals - API Reference
-    ##
     $(IDF_PATH)/components/hal/include/hal/adc_types.h \
     $(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/adc_channel.h \
     $(IDF_PATH)/components/driver/include/driver/adc_common.h \
@@ -130,39 +108,22 @@ INPUT = \
     $(IDF_PATH)/components/hal/include/hal/uart_types.h \
     $(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/uart_channel.h \
     $(IDF_PATH)/components/driver/include/driver/uart.h \
-    ## esp_netif - API Reference
     $(IDF_PATH)/components/esp_netif/include/esp_netif.h \
     $(IDF_PATH)/components/esp_netif/include/esp_netif_net_stack.h \
-    ##
-    ## Protocols - API Reference
-    ##
-    ## ESP-TLS
     $(IDF_PATH)/components/esp-tls/esp_tls.h \
-    ## MQTT
     $(IDF_PATH)/components/mqtt/esp-mqtt/include/mqtt_client.h \
-    ## ICMP-ECHO
     $(IDF_PATH)/components/lwip/include/apps/ping/ping_sock.h \
-    ## SNTP
     $(IDF_PATH)/components/lwip/include/apps/esp_sntp.h \
-    ## mDNS
     $(IDF_PATH)/components/mdns/include/mdns.h \
     $(IDF_PATH)/components/esp_http_client/include/esp_http_client.h \
     $(IDF_PATH)/components/esp_websocket_client/include/esp_websocket_client.h \
-    ## HTTP / HTTPS Server
     $(IDF_PATH)/components/esp_http_server/include/esp_http_server.h \
     $(IDF_PATH)/components/esp_https_server/include/esp_https_server.h \
-    ## ESP Local Ctrl
     $(IDF_PATH)/components/esp_local_ctrl/include/esp_local_ctrl.h \
-    ## ESP Serial Slave Link
     $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \
     $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
     $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h \
-    ## ESP Certificate Bundle
     $(IDF_PATH)/components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h \
-    ##
-    ## Provisioning - API Reference
-    ##
-    ## Protocol Communication
     $(IDF_PATH)/components/protocomm/include/common/protocomm.h \
     $(IDF_PATH)/components/protocomm/include/security/protocomm_security.h \
     $(IDF_PATH)/components/protocomm/include/security/protocomm_security0.h \
@@ -170,119 +131,70 @@ INPUT = \
     $(IDF_PATH)/components/protocomm/include/transports/protocomm_ble.h \
     $(IDF_PATH)/components/protocomm/include/transports/protocomm_console.h \
     $(IDF_PATH)/components/protocomm/include/transports/protocomm_httpd.h \
-    ## WiFi Provisioning
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/manager.h \
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
     $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \
-    ##
-    ## Storage - API Reference
-    ##
-    ## SPI Flash and Partition APIs
     $(IDF_PATH)/components/hal/include/hal/spi_flash_types.h \
     $(IDF_PATH)/components/spi_flash/include/esp_flash_spi_init.h \
     $(IDF_PATH)/components/spi_flash/include/esp_flash.h \
     $(IDF_PATH)/components/spi_flash/include/esp_partition.h \
     $(IDF_PATH)/components/bootloader_support/include/esp_flash_encrypt.h \
-    ## SPIFFS
     $(IDF_PATH)/components/spiffs/include/esp_spiffs.h \
-    ## SD/MMC Card Host
     $(IDF_PATH)/components/driver/include/driver/sdmmc_types.h \
     $(IDF_PATH)/components/sdmmc/include/sdmmc_cmd.h \
     $(IDF_PATH)/components/driver/include/driver/sdmmc_host.h \
     $(IDF_PATH)/components/driver/include/driver/sdspi_host.h \
-    ## SDIO slave
     $(IDF_PATH)/components/hal/include/hal/sdio_slave_types.h \
     $(IDF_PATH)/components/driver/include/driver/sdio_slave.h \
-    ## Non-Volatile Storage
     $(IDF_PATH)/components/nvs_flash/include/nvs.h \
     $(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \
-    ## OpenThread
     $(IDF_PATH)/components/openthread/include/esp_openthread.h \
     $(IDF_PATH)/components/openthread/include/esp_openthread_lock.h \
     $(IDF_PATH)/components/openthread/include/esp_openthread_types.h \
     $(IDF_PATH)/components/openthread/include/openthread-core-esp32x-config.h \
-    ## Virtual Filesystem
     $(IDF_PATH)/components/vfs/include/esp_vfs.h \
     $(IDF_PATH)/components/vfs/include/esp_vfs_dev.h \
     $(IDF_PATH)/components/vfs/include/esp_vfs_semihost.h \
-    ## FAT Filesystem
-    ## NOTE: for two lines below header_file.inc is not used
     $(IDF_PATH)/components/fatfs/vfs/esp_vfs_fat.h \
     $(IDF_PATH)/components/fatfs/diskio/diskio_impl.h \
     $(IDF_PATH)/components/fatfs/diskio/diskio_sdmmc.h \
     $(IDF_PATH)/components/fatfs/diskio/diskio_wl.h \
     $(IDF_PATH)/components/fatfs/diskio/diskio_rawflash.h \
-    ## Wear Levelling
     $(IDF_PATH)/components/wear_levelling/include/wear_levelling.h \
-    ##
-    ## System - API Reference
-    ##
-    ## ESP Console
     $(IDF_PATH)/components/console/esp_console.h \
-    ## Memory Allocation
     $(IDF_PATH)/components/heap/include/esp_heap_caps.h \
     $(IDF_PATH)/components/heap/include/esp_heap_trace.h \
     $(IDF_PATH)/components/heap/include/esp_heap_caps_init.h \
     $(IDF_PATH)/components/heap/include/multi_heap.h \
-    ## Interrupt Allocation
     $(IDF_PATH)/components/esp_hw_support/include/esp_intr_alloc.h \
-    ## Watchdogs
-    ## NOTE: for two lines below header_file.inc is not used
     $(IDF_PATH)/components/esp_system/include/esp_int_wdt.h \
     $(IDF_PATH)/components/esp_system/include/esp_task_wdt.h \
     $(IDF_PATH)/components/esp_hw_support/include/esp_crc.h \
-    ## Hooks
     $(IDF_PATH)/components/esp_system/include/esp_freertos_hooks.h \
-    ## Inter-Processor Call
     $(IDF_PATH)/components/esp_ipc/include/esp_ipc.h \
-    ## Call Function with External stack
     $(IDF_PATH)/components/esp_system/include/esp_expression_with_stack.h \
-    ## Over The Air Updates (OTA)
     $(IDF_PATH)/components/app_update/include/esp_ota_ops.h \
-    ## ESP HTTPS OTA
     $(IDF_PATH)/components/esp_https_ota/include/esp_https_ota.h \
-    ## Sleep
     $(IDF_PATH)/components/esp_hw_support/include/esp_sleep.h \
-    ## Async memory copy
     $(IDF_PATH)/components/esp_hw_support/include/esp_async_memcpy.h \
-    ## Logging
     $(IDF_PATH)/components/log/include/esp_log.h \
     $(IDF_PATH)/components/esp_rom/include/esp_rom_sys.h \
-    ## Base MAC address
-    ## NOTE: for line below header_file.inc is not used
     $(IDF_PATH)/components/esp_system/include/esp_system.h \
-    ## IDF version
     $(IDF_PATH)/components/esp_common/include/esp_idf_version.h \
-    ##
-    ## ULP Coprocessor - API Guides
-    ##
-    ## NOTE: for line below header_file.inc is not used
     $(IDF_PATH)/components/ulp/include/ulp_common.h \
-    ##
-    ## Application Level Tracing - API Reference
-    ##
     $(IDF_PATH)/components/app_trace/include/esp_app_trace.h \
     $(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \
-    ### Power management
     $(IDF_PATH)/components/esp_pm/include/esp_pm.h \
     $(IDF_PATH)/components/esp_pm/include/$(IDF_TARGET)/pm.h \
-    ### esp_timer, High Resolution Timer
     $(IDF_PATH)/components/esp_timer/include/esp_timer.h \
-    ### esp_event, Event Loop Library
     $(IDF_PATH)/components/esp_event/include/esp_event.h \
     $(IDF_PATH)/components/esp_event/include/esp_event_base.h \
-    ### eFuse Manager
     $(IDF_PATH)/components/efuse/include/esp_efuse.h \
-    ### App Image Format
     $(IDF_PATH)/components/bootloader_support/include/esp_app_format.h \
-    ### ESP Pthread parameters
     $(IDF_PATH)/components/pthread/include/esp_pthread.h \
-    ###
-    ### FreeRTOS
-    ###
     $(IDF_PATH)/components/freertos/include/freertos/task.h \
     $(IDF_PATH)/components/freertos/include/freertos/queue.h \
     $(IDF_PATH)/components/freertos/include/freertos/semphr.h \
@@ -290,22 +202,16 @@ INPUT = \
     $(IDF_PATH)/components/freertos/include/freertos/event_groups.h \
     $(IDF_PATH)/components/freertos/include/freertos/stream_buffer.h \
     $(IDF_PATH)/components/freertos/include/freertos/message_buffer.h \
-    ### Ringbuffer
     $(IDF_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
-    ### Helper functions for error codes
     $(IDF_PATH)/components/esp_common/include/esp_err.h \
-    ### Check macros
     $(IDF_PATH)/components/esp_common/include/esp_check.h \
-    ### System APIs
     $(IDF_PATH)/components/esp_system/include/esp_system.h \
-    ### Modbus controller component header file
     $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_common.h \
     $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \
     $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_master.h \
-     ### Performance Monitor component header file
-     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
-     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
-     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h
+    $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
+    $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
+    $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h
 
 
 ## Target specific headers are in seperate Doxyfile files

docs/en/api-guides/blufi.rst

@@ -426,7 +426,7 @@ Here are two "*", because the length of the data to be emitted is unknown that r
 
 .. code-block:: c
 
-   typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len)
+   typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
 
 The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
 

docs/zh_CN/api-guides/blufi.rst

@@ -59,7 +59,7 @@ ESP32 配网流程
         node_height = 60;
         edge_length = 380;
         span_height = 10;
-        default_fontsize = 12; 
+        default_fontsize = 12;
 
         Phone <- ESP32 [label="广播"];
         Phone -> ESP32 [label="建立 GATT 链接"];
@@ -139,17 +139,17 @@ Ack 帧格式（8 bit）：
 |                  |                       |                    |
 +------------------+-----------------------+--------------------+
 | MSB - CheckSum   | 2                                          |
-+------------------+--------------------------------------------+ 
++------------------+--------------------------------------------+
 
 1. Type
 
    类型域，占 1 byte。分为 Type 和 Subtype（子类型域）两部分, Type 占低 2 bit，Subtype 占高 6 bit。
-   
+
    * 控制帧，暂不进行加密，可校验；
-   
+
    * 数据帧，可加密，可校验。
 
- **1.1 控制帧 (0x0 b’00)** 
+ **1.1 控制帧 (0x0 b’00)**
 
   +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+
   | 控制帧 (二进制)  | 含义                              | 解释                                                           | 备注                                                                 |
@@ -333,7 +333,7 @@ Ack 帧格式（8 bit）：
 2. Frame Control
 
    帧控制域，占 1 byte，每个 bit 表示不同含义。
-   
+
    +----------------+-------------------------------------------------------------------------------------------------------------------------------+
    | 位             | 含义                                                                                                                          |
    +================+===============================================================================================================================+
@@ -376,11 +376,11 @@ Ack 帧格式（8 bit）：
 3. Sequence Control
 
    序列控制域。帧发送时，无论帧的类型是什么，序列 (Sequence) 都会自动加 1，用来防止重放攻击 (Replay Attack)。每次重现连接后，序列清零。
-   
+
 4. Length
 
    Data 域的长度，不包含 CheckSum。
-   
+
 5. Data
 
    不同的 Type 或 Subtype，Data 域的含义均不同。请参考上方表格。
@@ -388,7 +388,7 @@ Ack 帧格式（8 bit）：
 6. CheckSum
 
    此域为 2 byte 的校验，用来校验『序列 + 数据长度 + 明文数据』。
-   
+
 ESP32 端的安全实现
 ------------------
 
@@ -415,29 +415,29 @@ ESP32 端的安全实现
    typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free);
 
 该函数用来接收协商期间的正常数据 (normal data)，处理完成后，需要将待发送的数据使用 output_data 和 output_len 传出。
-   
+
 BluFi 会在调用完 negotiate_data_handler 后，发送 negotiate_data_handler 传出的 output_data。
-   
+
 这里的两个『*』，因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，通过 need_free 通知是否需要释放内存。
- 
+
 .. code-block:: c
 
-   typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len);	
-  
+   typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
+
 加密和解密的数据长度必须一致。其中 iv8 为帧的 8 bit 序列 (sequence)，可作为 iv 的某 8 bit 来使用。
-  
+
 .. code-block:: c
-   
+
    typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
 
 加密和解密的数据长度必须一致。其中 iv8 为帧的 8 bit 序列 (sequence)，可作为 iv 的某 8 bit 来使用。
-   
+
 .. code-block:: c
-   
+
    typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len);
-   
+
 该函数用来计算 CheckSum，返回值为 CheckSum 的值。BluFi 会使用该函数返回值与包末尾的 CheckSum 做比较。
-      
+
 GATT 相关说明
 -------------