From 531cab5fc4640c80f50ee62e4cb8073fa639b0a5 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 12 Apr 2021 08:44:04 +0800 Subject: [PATCH] docs: fix doxygen compile warnings for doxygen 1.9.1 Newer versions of doxygen will give warnings for comments in INPUT lists Delete all comment lines to fix these warnings, our folder structure stil gives an OK overview of what we are including --- .../bluedroid/api/include/api/esp_blufi_api.h | 3 +- .../bluedroid/api/include/api/esp_gattc_api.h | 2 +- .../api/include/api/esp_hf_client_api.h | 2 +- docs/Doxyfile | 84 ------------------- docs/en/api-guides/blufi.rst | 12 +-- docs/zh_CN/api-guides/blufi.rst | 40 ++++----- 6 files changed, 30 insertions(+), 113 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h b/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h index f17fcbc228..0d4b8662f0 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h +++ b/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 diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 08a8b4b811..407ebcf9b2 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -258,7 +258,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 */ diff --git a/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h b/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h index 8e3dc956b7..2e9cd82383 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h @@ -271,7 +271,7 @@ typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t l * buffer is allocated inside bluetooth protocol stack and will be released after * invoke of the callback is finished. * @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); diff --git a/docs/Doxyfile b/docs/Doxyfile index 497bd198ca..2e8bac2975 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -21,45 +21,30 @@ PROJECT_NAME = "ESP32 Programming Guide" ## and used to include in API reference documentation INPUT = \ - ## - ## Wi-Fi - API Reference - ## ../../components/esp_wifi/include/esp_wifi.h \ ../../components/esp_wifi/include/esp_wifi_types.h \ ../../components/esp_wifi/include/esp_smartconfig.h \ ../../components/esp_wifi/include/esp_now.h \ - ## Mesh - API Reference ../../components/esp_wifi/include/esp_mesh.h \ - ## Event loop - API Reference ../../components/esp_event/include/esp_event.h \ ../../components/esp_event/include/esp_event_base.h \ ../../components/esp_event/include/esp_event_legacy.h \ - ## Bluetooth - API Reference - ## Controller && VHCI ../../components/bt/include/esp_bt.h \ - ## Bluetooth COMMON - ## Issue with __attribute__ ../../components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \ ../../components/bt/host/bluedroid/api/include/api/esp_bt_main.h \ ../../components/bt/host/bluedroid/api/include/api/esp_bt_device.h \ - ## Bluetooth LE ../../components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \ - ## Issue with __attribute__ ../../components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \ ../../components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \ ../../components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \ ../../components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \ - ## Bluetooth Classic ../../components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \ - ## Issue with __attribute__ ../../components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \ ../../components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \ ../../components/bt/host/bluedroid/api/include/api/esp_spp_api.h \ ../../components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \ ../../components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \ - ## NimBLE related Bluetooth APIs ../../components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \ - ## ESP BLE Mesh APIs ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \ ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \ ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \ @@ -73,16 +58,10 @@ INPUT = \ ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \ ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \ ../../components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \ - ## - ## Ethernet - API Reference - ## ../../components/esp_eth/include/esp_eth.h \ ../../components/esp_eth/include/esp_eth_com.h \ ../../components/esp_eth/include/esp_eth_mac.h \ ../../components/esp_eth/include/esp_eth_phy.h \ - ## - ## Peripherals - API Reference - ## ../../components/driver/include/driver/adc.h \ ../../components/driver/include/driver/can.h \ ../../components/driver/include/driver/dac.h \ @@ -108,28 +87,15 @@ INPUT = \ ../../components/soc/esp32/include/soc/touch_channel.h \ ../../components/soc/esp32/include/soc/uart_channel.h \ ../../components/soc/esp32/include/soc/rtc_gpio_channel.h \ - ## tcpip_adapter - API Reference ../../components/tcpip_adapter/include/tcpip_adapter.h \ - ## - ## Protocols - API Reference - ## - ## ESP-TLS ../../components/esp-tls/esp_tls.h \ - ## MQTT ../../components/mqtt/esp-mqtt/include/mqtt_client.h \ - ## mDNS ../../components/mdns/include/mdns.h \ ../../components/esp_http_client/include/esp_http_client.h \ ../../components/esp_websocket_client/include/esp_websocket_client.h \ - ## HTTP / HTTPS Server ../../components/esp_http_server/include/esp_http_server.h \ ../../components/esp_https_server/include/esp_https_server.h \ - ## ESP Local Ctrl ../../components/esp_local_ctrl/include/esp_local_ctrl.h \ - ## - ## Provisioning - API Reference - ## - ## Protocol Communication ../../components/protocomm/include/common/protocomm.h \ ../../components/protocomm/include/security/protocomm_security.h \ ../../components/protocomm/include/security/protocomm_security0.h \ @@ -137,119 +103,69 @@ INPUT = \ ../../components/protocomm/include/transports/protocomm_ble.h \ ../../components/protocomm/include/transports/protocomm_console.h \ ../../components/protocomm/include/transports/protocomm_httpd.h \ - ## WiFi Provisioning ../../components/wifi_provisioning/include/wifi_provisioning/manager.h \ ../../components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \ ../../components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \ ../../components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \ ../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \ ../../components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \ - ## - ## Storage - API Reference - ## - ## SPI Flash and Partition APIs ../../components/spi_flash/include/esp_flash_spi_init.h \ ../../components/spi_flash/include/esp_flash.h \ ../../components/spi_flash/include/esp_partition.h \ ../../components/bootloader_support/include/esp_flash_encrypt.h \ ../../components/soc/include/hal/spi_flash_types.h \ - ## SPIFFS ../../components/spiffs/include/esp_spiffs.h \ - ## SD/MMC Card Host ../../components/sdmmc/include/sdmmc_cmd.h \ ../../components/driver/include/driver/sdmmc_host.h \ ../../components/driver/include/driver/sdmmc_types.h \ ../../components/driver/include/driver/sdspi_host.h \ - ## SDIO slave ../../components/driver/include/driver/sdio_slave.h \ - ## Non-Volatile Storage ../../components/nvs_flash/include/nvs.h \ ../../components/nvs_flash/include/nvs_flash.h \ - ## Virtual Filesystem ../../components/vfs/include/esp_vfs.h \ ../../components/vfs/include/esp_vfs_dev.h \ ../../components/vfs/include/esp_vfs_semihost.h \ - ## FAT Filesystem - ## NOTE: for two lines below header_file.inc is not used ../../components/fatfs/vfs/esp_vfs_fat.h \ ../../components/fatfs/diskio/diskio_impl.h \ ../../components/fatfs/diskio/diskio_sdmmc.h \ ../../components/fatfs/diskio/diskio_wl.h \ ../../components/fatfs/diskio/diskio_rawflash.h \ - ## Wear Levelling ../../components/wear_levelling/include/wear_levelling.h \ - ## - ## System - API Reference - ## - ## Memory Allocation # ../../components/heap/include/esp_heap_caps.h \ ../../components/heap/include/esp_heap_trace.h \ ../../components/heap/include/esp_heap_caps_init.h \ ../../components/heap/include/multi_heap.h \ - ## Himem ../../components/esp32/include/esp32/himem.h \ - ## Interrupt Allocation ../../components/esp32/include/esp_intr_alloc.h \ - ## Watchdogs - ## NOTE: for two lines below header_file.inc is not used ../../components/esp_common/include/esp_int_wdt.h \ ../../components/esp_common/include/esp_task_wdt.h \ - ## Hooks ../../components/esp_common/include/esp_freertos_hooks.h \ - ## Inter-Processor Call ../../components/esp_common/include/esp_ipc.h \ - ## Over The Air Updates (OTA) ../../components/app_update/include/esp_ota_ops.h \ - ## ESP HTTPS OTA ../../components/esp_https_ota/include/esp_https_ota.h \ - ## Sleep ../../components/esp32/include/esp_sleep.h \ - ## Logging ../../components/log/include/esp_log.h \ - ## Base MAC address - ## NOTE: for line below header_file.inc is not used ../../components/esp_common/include/esp_system.h \ - ## IDF version ../../components/esp_common/include/esp_idf_version.h \ - ## - ## ULP Coprocessor - API Guides - ## - ## NOTE: for line below header_file.inc is not used ../../components/ulp/include/esp32/ulp.h \ - ## - ## Application Level Tracing - API Reference - ## ../../components/app_trace/include/esp_app_trace.h \ ../../components/app_trace/include/esp_sysview_trace.h \ - ### Power management ../../components/esp_common/include/esp_pm.h \ ../../components/esp32/include/esp32/pm.h \ - ### esp_timer, High Resolution Timer ../../components/esp_common/include/esp_timer.h \ - ### esp_event, Event Loop Library ../../components/esp_event/include/esp_event.h \ ../../components/esp_event/include/esp_event_base.h \ - ### eFuse Manager ../../components/efuse/include/esp_efuse.h \ - ### App Image Format ../../components/bootloader_support/include/esp_app_format.h \ - ### ESP Pthread parameters ../../components/pthread/include/esp_pthread.h \ - ### - ### FreeRTOS - ### ../../components/freertos/include/freertos/task.h \ ../../components/freertos/include/freertos/queue.h \ ../../components/freertos/include/freertos/semphr.h \ ../../components/freertos/include/freertos/timers.h \ ../../components/freertos/include/freertos/event_groups.h \ - ### Ringbuffer ../../components/esp_ringbuf/include/freertos/ringbuf.h \ - ### Helper functions for error codes ../../components/esp_common/include/esp_err.h \ - ### System APIs ../../components/esp_common/include/esp_system.h \ - ### Modbus controller component header file ../../components/freemodbus/common/include/esp_modbus_common.h \ ../../components/freemodbus/common/include/esp_modbus_slave.h \ ../../components/freemodbus/common/include/esp_modbus_master.h diff --git a/docs/en/api-guides/blufi.rst b/docs/en/api-guides/blufi.rst index 97b04dff2c..9516d09140 100644 --- a/docs/en/api-guides/blufi.rst +++ b/docs/en/api-guides/blufi.rst @@ -55,7 +55,7 @@ The flow chart of BluFi node_height = 60; edge_length = 380; span_height = 10; - default_fontsize = 12; + default_fontsize = 12; Phone <- ESP32 [label="Advertising"]; Phone -> ESP32 [label="Create GATT connection"]; @@ -144,8 +144,8 @@ The format of Ack Frame（8 bit）： * The control frame is not encrypted for the time being and supports to be verified; * The data frame supports to be encrypted and verified. - - **1.1 Control Frame (0x0 b’00)** + + **1.1 Control Frame (0x0 b’00)** +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ | Control Frame (Binary) | Implication | Explanation | Note | @@ -411,10 +411,10 @@ The Security Implementation of ESP32 It is added to the Sequence field and used during the checksum verification. For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. - + The application layer needs to register several security-related functions to BluFi: -.. code-block:: c +.. code-block:: c typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free) @@ -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. diff --git a/docs/zh_CN/api-guides/blufi.rst b/docs/zh_CN/api-guides/blufi.rst index 6b15a98731..6d443d6f26 100644 --- a/docs/zh_CN/api-guides/blufi.rst +++ b/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 相关说明 -------------