为 C++ 代码添加文档¶

C++ 的文档通过 Javadoc 风格注释提供，并使用 Sphinx、Doxygen 和 Breathe 生成。

文档保存在具有 .h 扩展名的头文件中，以及 .cpp、cu 和 cuh 文件中。在这些文件中，#ifndef DOXYGEN_THIS_WILL_BE_SKIPPED 和 #endif 之间的所有内容都将从 HTML 输出中隐藏。添加函数描述时，请确保 #ifndef 和 #endif 配置正确。

请遵循以下说明来记录、生成和发布新的 C++ 文档字符串

API 方法按组标签分组，以便在 Sphinx 中更好地组织。如果目标方法的所需方法组尚未定义，请在相关头文件顶部附近使用 @defgroup 命令定义它。
```
/// @defgroup example-method-group Example Method Group
/// This is a description of the example method group.
```

将文档字符串直接添加到目标方法的声明上方。至少，请添加以下内容的描述：

方法的函数行为
类型参数，用 @tparam 标签表示
参数，用 @param 标签表示
返回值，用 @return 标签表示
可能抛出的异常（如果适用），用 @throw 标签表示

如有需要，还应添加 @note、@warning 和 @see 等其他命令。

这是一个 C++ 文档字符串示例

/// @ingroup example-method-group
///
/// @brief A very short description of `example_method`.
///
/// Here is a much longer description of `example_method` with code examples:
///
/// **Example:**
/// ```python
/// # Here is a Python code block
/// def foo(lst: list[int]) -> list[int]:
///   return [ x ** 2 for x in lst ]
/// ```
///
/// And here is a verbatim-text diagram example:
///
/// @code{.unparsed}
///   .------+---------------------------------.-----------------------------
///   |            Block A (first)             |       Block B (second)
///
///   +------+------+--------------------------+------+------+---------------
///   | Next | Prev |   usable space           | Next | Prev | usable space..
///   +------+------+--------------------------+------+--+---+---------------
///   ^  |                                     ^         |
///   |  '-------------------------------------'         |
///   |                                                  |
///   '----------- Block B's prev points to Block A -----'
/// @endcode
///
/// @tparam T Description of `T`
/// @tparam Alignment Description of the `Alignment` value
/// @param param1 Description of `param1`
/// @param param2 Description of `param2`
///
/// @return Description of the method's return value.
///
/// @throw std::bad_alloc if allocation failed
/// @throw std::logic_error if a logic error occurs
///
/// @note This is an example note.
///
/// @warning This is an example warning.
///
/// @see For more info on Doxygen docstrings, see
/// <a href="https://doxygen.cn/manual/commands.html#cmdlink">here</a>.
template <typename T, std::size_t Alignment>
int32_t example_method(T param1, float param2);

在 Sphinx 文档方面，在相应的 .rst 文件中添加 doxygengroup 指令。如果不存在与相应头文件同名的 .rst 文件，则创建一个新的，其名称与头文件相同。使用上面的示例
```
.. doxygengroup:: example-method-group
  :content-only:
```
确保 .rst 文件已包含在 index.rst 的 toctree 中（例如 FBGEMM_GPU C++ API）。
C++ 源头文件必须位于 Doxygen.ini 文件中 INPUT 参数列出的目录之一。通常，这已经处理好了，但如果它位于未列出的目录中，请务必将目录路径追加到该参数。
通过本地构建文档（请参阅构建文档）或提交 PR 以进行 Netlify 预览来验证更改。

上面的 Doxygen 示例生成了以下 HTML 输出

template<typename T, std::size_t Alignment> int32_t example_method(T param1, float param2)¶

example_method 的一个非常简短的描述。

这里是 example_method 的一个长得多的描述，包含代码示例

示例

# Here is a Python code block
def foo(lst: list[int]) -> list[int]:
  return [ x ** 2 for x in lst ]

这是一个原始文本图表示例

.------+---------------------------------.-----------------------------
|            Block A (first)             |       Block B (second)

+------+------+--------------------------+------+------+---------------
| Next | Prev |   usable space           | Next | Prev | usable space..
+------+------+--------------------------+------+--+---+---------------
^  |                                     ^         |
|  '-------------------------------------'         |
|                                                  |
'----------- Block B's prev points to Block A -----'

另请参阅

有关 Doxygen 文档字符串的更多信息，请参阅此处。

注意

这是一个注释示例。

警告

这是一个警告示例。

模板参数:

T – T 的描述
Alignment – Alignment 值的描述

参数:

param1 – param1 的描述
param2 – param2 的描述

抛出:

std::bad_alloc – 如果分配失败
std::logic_error – 如果发生逻辑错误

返回:

描述方法的返回值。

为 C++ 代码添加文档¶

文档

教程

资源