为 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.cpp.org.cn/manual/commands.html#cmdlink">here</a>.
template <typename T, std::size_t Alignment>
int32_t example_method(T param1, float param2);

在 Sphinx 文档方面，将 doxygengroup 指令添加到相应的 .rst 文件。如果相应头文件的 .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++ 代码添加文档¶

文档

教程

资源