# API 文档模板

[English]

备注

说明

1. 使用此文件 (docs/zh_CN/api-reference/template.rst) 作为 API 参考文档模板。

2. API 参考文档需和 API 的头文件名称保持一致。

3. 使用 `..include::` 从 API 文件夹中添加相应的说明文件。

   > - README.rst

   > - example.rst

   > - ...

4. 可选择在此文件中直接提供描述。

5. 完成后，删除所有的说明信息（类似本说明）和多余的头部信息。

## 概述

备注

撰写说明

1. 提供概述，简要说明 API 的用途和使用方法。

2. 必要时提供代码片段，以说明特定函数的功能。

3. 用此 文档 中介绍的方式区分不同的章节标题：

   > - `#` 用于设置各部分，标题上下同时标记

   > - `*` 用于设置章标题，标题上下同时标记

   > - `=` 用于设置节标题

   > - `-` 用于设置小节标题

   > - `^` 用于设置小小节标题

   > - `"` 用于设置段落标题

## 应用示例

备注

撰写说明

1. 准备一个或多个实际示例，展示此 API 的功能。

2. 每个示例应遵循 `esp-idf/examples/` 文件夹中项目的模式。

3. 将示例放在此文件夹中，添加 `README.md` 文件。

4. 在 `README.md` 中对展示的功能进行概述。

5. 良好的概述让读者能够充分理解示例，而无需参考源代码。

6. 按照示例的复杂程度，将代码描述分解成几个部分，并对每部分的功能进行概述。

7. 必要时，添加流程图和应用程序的输出截图。

8. 最后为本章节的每个示例添加对应链接，示例文件夹应位于 `esp-idf/examples/` 中。

## API 参考

备注

撰写说明

1. ESP-IDF 仓库通过 用 Doxygen 从头文件中检索代码标记 的方式自动更新 API 参考文档。

2. 通过调用 Sphinx 扩展工具 `esp_extensions/run_doxygen.py`，对 docs/doxygen/Doxyfile 中 `INPUT` 语句列出的所有头文件进行更新。

3. `INPUT` 语句的每一行（以 `##` 开头的注释除外）都包含一个到头文件 `*.h` 的路径，用于生成相应的 `*.inc` 文件:

       ##
       ## Wi-Fi - API Reference
       ##
       ../components/esp32/include/esp_wifi.h \
       ../components/esp32/include/esp_smartconfig.h \

4. 头文件被展开时， `sdkconfig.h` 中默认定义的宏以及在 SOC 特定 `include/soc/*_caps.h` 头文件中定义的宏都会被展开。这样，头文件就可以根据 `IDF_TARGET` 的值来添加或排除相关内容。

5. `*.inc` 文件中包含每次文档构建时自动生成的 API 成员格式化参考。所有 `*.inc` 文件都位于 Sphinx 的 `_build` 路径下。如需查看生成指令，以 `esp_wifi.h` 为例，运行 `python gen-dxd.py esp32/include/esp_wifi.h`。

6. 用以下语句在文档中显示 `*.inc` 文件的内容:

       .. include-build-file:: inc/esp_wifi.inc

   参考示例：docs/en/api-reference/network/esp_wifi.rst

7. 你也可以不用 `*.inc` 文件，而使用自己的方式描述 API。参考示例：docs/en/api-reference/storage/fatfs.rst。

   以下为常见的 `.. doxygen...::` 指令：

   > - 函数 - `.. doxygenfunction:: name_of_function`

   > - 联合体 - `.. doxygenunion:: name_of_union`

   > - 结构体 - `.. doxygenstruct:: name_of_structure` 和 `:members:`

   > - 宏 - `.. doxygendefine:: name_of_define`

   > - 类定义 - `.. doxygentypedef:: name_of_type`

   > - 枚举 - `.. doxygenenum:: name_of_enumeration`

   如需更多信息，请参考 Breathe 文档。

   使用 link custom role 指令添加指向头文件的链接，如下所示:

       * :component_file:`path_to/header_file.h`

8. 在任何情况下，要生成 API 参考文档，应该更新文件 docs/doxygen/Doxyfile 并将其中的路径更新为正在添加文档的 `*.h` 头文件的路径。

9. 更改提交并构建文档后，可以查看文档的渲染效果。如有需要，为相应的头文件 纠正注释。

提供有关此文档的反馈