Skip to content

Commit 9c91ca4

Browse files
tore-espressiftore-espressif
committed
docs: Review comments
1 parent 38b52fe commit 9c91ca4

File tree

10 files changed

+64
-37
lines changed

10 files changed

+64
-37
lines changed

‎docs/Doxyfile‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ PROJECT_BRIEF = "ESP-IDF USB Host and Device Drivers"
1313
## and used to include in API reference documentation
1414
INPUT = \
1515
$(PROJECT_PATH)/host/usb/include/usb/usb_host.h \
16+
$(PROJECT_PATH)/host/usb/include/usb/usb_helpers.h \
17+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_stack.h \
18+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_ch9.h \
19+
$(PROJECT_PATH)/host/usb/include/usb/usb_types_ch11.h \
1620
$(PROJECT_PATH)/device/esp_tinyusb/include/tinyusb.h
1721

1822
WARN_NO_PARAMDOC = YES
@@ -23,7 +27,10 @@ ENABLE_PREPROCESSING = YES
2327
MACRO_EXPANSION = YES
2428
EXPAND_ONLY_PREDEF = YES
2529
PREDEFINED = \
26-
$(ENV_DOXYGEN_DEFINES)
30+
$(ENV_DOXYGEN_DEFINES) \
31+
__DOXYGEN__=1 \
32+
__attribute__(x)= \
33+
ESP_STATIC_ASSERT()=
2734

2835
## Do not complain about not having dot
2936
##

‎docs/en/conf.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,15 @@
2020
import datetime
2121

2222
current_year = datetime.datetime.now().year
23+
start_year = 2025
24+
25+
if current_year == start_year:
26+
copyright = '{}, Espressif Systems (Shanghai) Co., Ltd'.format(start_year)
27+
else:
28+
copyright = '{} - {}, Espressif Systems (Shanghai) Co., Ltd'.format(start_year, current_year)
2329

2430
# General information about the project.
2531
project = u'ESP-USB Programming Guide'
26-
copyright = '2025 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(current_year) # noqa: A001
2732
author = u'Espressif Systems'
2833
pdf_title = u'ESP-USB Programming Guide'
2934

‎docs/en/index.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2-
..
3-
.. SPDX-License-Identifier: Apache-2.0
4-
51
ESP-USB Programming Guide
62
==========================
73

‎docs/en/introduction.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2-
..
3-
.. SPDX-License-Identifier: Apache-2.0
4-
51
Introduction
62
============
73

‎docs/en/usb_host.rst‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -700,11 +700,23 @@ API Reference
700700

701701
The API of the USB Host Library is separated into the following header files. However, it is sufficient for applications to only ``#include "usb/usb_host.h"`` and all USB Host Library headers will also be included.
702702

703-
- `usb/include/usb/usb_host.h` contains the functions and types of the USB Host Library.
704-
- `usb/include/usb/usb_helpers.h` contains various helper functions that are related to the USB protocol such as descriptor parsing.
705-
- `usb/include/usb/usb_types_stack.h` contains types that are used across multiple layers of the USB Host stack.
706-
- `usb/include/usb/usb_types_ch9.h` contains types and macros related to Chapter 9 of the USB2.0 specification, i.e., descriptors and standard requests.
707-
- `usb/include/usb/usb_types_ch11.h` contains types and macros related to Chapter 11 of the USB2.0 specification, i.e., hub specifications.
703+
- `host/usb/include/usb/usb_host.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_host.h>`__ contains the functions and types of the USB Host Library.
704+
- `host/usb/include/usb/usb_helpers.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_helpers.h>`__ contains various helper functions that are related to the USB protocol such as descriptor parsing.
705+
- `host/usb/include/usb/usb_types_stack.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_stack.h>`__ contains types that are used across multiple layers of the USB Host stack.
706+
- `host/usb/include/usb/usb_types_ch9.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_ch9.h>`__ contains types and macros related to Chapter 9 of the USB2.0 specification, i.e., descriptors and standard requests.
707+
- `host/usb/include/usb/usb_types_ch11.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_ch11.h>`__ contains types and macros related to Chapter 11 of the USB2.0 specification, i.e., hub specifications.
708+
709+
710+
.. include-build-file:: inc/usb_host.inc
711+
712+
.. include-build-file:: inc/usb_helpers.inc
713+
714+
.. include-build-file:: inc/usb_types_stack.inc
715+
716+
.. include-build-file:: inc/usb_types_ch9.inc
717+
718+
.. include-build-file:: inc/usb_types_ch11.inc
719+
708720

709721
Header File
710722
^^^^^^^^^^^

‎docs/zh_CN/conf.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,15 @@
2020
import datetime
2121

2222
current_year = datetime.datetime.now().year
23+
start_year = 2025
24+
25+
if current_year == start_year:
26+
copyright = '{}, 乐鑫信息科技（上海）股份有限公司'.format(start_year)
27+
else:
28+
copyright = '{} - {}, 乐鑫信息科技（上海）股份有限公司'.format(start_year, current_year)
2329

2430
# General information about the project.
2531
project = u'ESP-USB 编程指南'
26-
copyright = '2025 - {}, 乐鑫信息科技（上海）股份有限公司'.format(current_year) # noqa: A001
2732
author = u'乐鑫信息科技（上海）股份有限公司'
2833
pdf_title = u'ESP-USB 编程指南'
2934

‎docs/zh_CN/index.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2-
..
3-
.. SPDX-License-Identifier: Apache-2.0
4-
51
ESP-USB Programming Guide
62
==========================
73

‎docs/zh_CN/introduction.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
2-
..
3-
.. SPDX-License-Identifier: Apache-2.0
4-
51
Introduction
62
============
73

‎docs/zh_CN/usb_host.rst‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -700,11 +700,23 @@ API 参考
700700

701701
USB 主机库的 API 包含以下头文件，但应用程序调用该 API 时只需 ``#include "usb/usb_host.h"``，就可以包含所有 USB 主机库的头文件。
702702

703-
- `usb/include/usb/usb_host.h` 包含 USB 主机库的函数和类型。
704-
- `usb/include/usb/usb_helpers.h` 包含与 USB 协议相关的各种辅助函数，如描述符解析等。
705-
- `usb/include/usb/usb_types_stack.h` 包含在 USB 主机栈的多个层次中使用的类型。
706-
- `usb/include/usb/usb_types_ch9.h` 包含了与 USB 2.0 规范中第 9 章相关的类型和宏，即描述符和标准请求。
707-
- `usb/include/usb/usb_types_ch11.h` 包含与 USB2.0 规范第 11 章相关的类型和宏，即集线器规范。
703+
- `host/usb/include/usb/usb_host.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_host.h>`__ 包含 USB 主机库的函数和类型。
704+
- `host/usb/include/usb/usb_helpers.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_helpers.h>`__ 包含与 USB 协议相关的各种辅助函数，如描述符解析等。
705+
- `host/usb/include/usb/usb_types_stack.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_stack.h>`__` 包含在 USB 主机栈的多个层次中使用的类型。
706+
- `host/usb/include/usb/usb_types_ch9.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_ch9.h>`__ 包含了与 USB 2.0 规范中第 9 章相关的类型和宏，即描述符和标准请求。
707+
- `host/usb/include/usb/usb_types_ch11.h <https://github.com/espressif/esp-usb/tree/master/host/usb/include/usb/usb_types_ch11.h>`__ 包含与 USB2.0 规范第 11 章相关的类型和宏，即集线器规范。
708+
709+
710+
.. include-build-file:: inc/usb_host.inc
711+
712+
.. include-build-file:: inc/usb_helpers.inc
713+
714+
.. include-build-file:: inc/usb_types_stack.inc
715+
716+
.. include-build-file:: inc/usb_types_ch9.inc
717+
718+
.. include-build-file:: inc/usb_types_ch11.inc
719+
708720

709721
头文件
710722
^^^^^^^

‎host/usb/include/usb/usb_types_ch11.h‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
2+
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
33
*
44
* SPDX-License-Identifier: Apache-2.0
55
*/
@@ -120,9 +120,9 @@ typedef enum {
120120
#define USB_PORT_STATUS_SIZE 4
121121

122122
/**
123-
* @brief USB Hub Port Status and Hub Change results
123+
* @brief USB Port Status and Change
124124
*
125-
* See USB 2.0 spec Table 11-19 and Table 11-20
125+
* @see USB 2.0 spec Table 11-21 and Table 11-22
126126
*/
127127
typedef struct {
128128
union {
@@ -141,7 +141,7 @@ typedef struct {
141141
uint8_t RESERVED_2 : 3; /**< Reserved field */
142142
};
143143
uint16_t val; /**< Port status value */
144-
} wPortStatus;
144+
} wPortStatus; /**< Port Status Field */
145145

146146
union {
147147
struct {
@@ -153,7 +153,7 @@ typedef struct {
153153
uint16_t RESERVED : 11; /**< Reserved field */
154154
};
155155
uint16_t val; /**< Port change value */
156-
} wPortChange;
156+
} wPortChange; /**< Port Change Field */
157157
} __attribute__((packed)) usb_port_status_t;
158158
ESP_STATIC_ASSERT(sizeof(usb_port_status_t) == USB_PORT_STATUS_SIZE, "Size of usb_port_status_t incorrect");
159159

@@ -163,7 +163,9 @@ ESP_STATIC_ASSERT(sizeof(usb_port_status_t) == USB_PORT_STATUS_SIZE, "Size of us
163163
#define USB_HUB_STATUS_SIZE 4
164164

165165
/**
166-
* @brief USB Hub Status
166+
* @brief USB Hub Status and Change
167+
*
168+
* @see USB 2.0 spec Table 11-19 and Table 11-20
167169
*/
168170
typedef struct {
169171
union {
@@ -173,15 +175,15 @@ typedef struct {
173175
uint16_t RESERVED : 14; /**< Reserved fields */
174176
};
175177
uint16_t val; /**< Hub status value */
176-
} wHubStatus;
178+
} wHubStatus; /**< Hub Status Field */
177179
union {
178180
struct {
179181
uint8_t C_HUB_LOCAL_POWER : 1; /**< 0 = No change has occurred to Local Power Status. 1 = Local Power Status has changed.*/
180182
uint8_t C_HUB_OVER_CURRENT : 1; /**< 0 = No change has occurred to the Over-Current Status. 1 = Over-Current Status has changed.*/
181183
uint16_t RESERVED : 14; /**< Reserved fields */
182184
};
183185
uint16_t val; /**< Hub change value */
184-
} wHubChange;
186+
} wHubChange; /**< Hub Change Field */
185187
} __attribute__((packed)) usb_hub_status_t;
186188
ESP_STATIC_ASSERT(sizeof(usb_hub_status_t) == USB_HUB_STATUS_SIZE, "Size of usb_hub_status_t incorrect");
187189

0 commit comments

Comments
 (0)