警告

This document is not updated for ESP32C5 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

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. 更改提交并构建文档后，可以查看文档的渲染效果。如有需要，为相应的头文件 纠正注释。

此文档对您有帮助吗？