快捷方式

为 C++ 代码添加文档

C++ 的文档通过 Javadoc 风格的注释提供,并使用 Sphinx、DoxygenBreathe 生成。

文档保存在扩展名为 .h 的头文件以及 .cppcucuh 文件中。在这些文件中,#ifndef DOXYGEN_THIS_WILL_BE_SKIPPED#endif 之间的所有内容都将从 HTML 输出中隐藏。当您向函数添加描述时,请确保 #ifndef#endif 配置正确。

按照以下说明文档化、生成和发布新的 C++ 文档字符串

  1. API 方法通过组标签分组在一起,以便在 Sphinx 中更好地组织。如果目标方法的所需方法组尚未定义,请在相关头文件的顶部附近使用 @defgroup 命令定义它

    /// @defgroup example-method-group Example Method Group
    /// This is a description of the example method group.
    
  2. 将文档字符串直接添加到目标方法声明的上方。至少,请添加以下描述:

    • 方法的功能行为

    • 类型参数,由 @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);
    
  3. 在 Sphinx 文档方面,将 doxygengroup 指令添加到相应的 .rst 文件。如果相应头文件的 .rst 文件不存在,则创建一个与头文件同名的新文件。使用上面的示例

    .. doxygengroup:: example-method-group
      :content-only:
    
  4. 确保 .rst 文件包含在 index.rsttoctree 中(例如 FBGEMM_GPU C++ API)。

  5. C++ 源代码头文件需要位于 Doxygen.iniINPUT 参数列出的目录之一。通常,这已经处理好了,但如果它位于未列出的目录中,请务必将目录路径附加到参数中。

  6. 通过在本地使用 构建文档 构建文档或提交 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 文档字符串的更多信息,请参阅此处

注意

这是一个示例注意。

警告

这是一个示例警告。

模板参数:
  • TT 的描述

  • AlignmentAlignment 值的描述

参数:
  • param1param1 的描述

  • param2param2 的描述

抛出:
  • std::bad_alloc – 如果分配失败

  • std::logic_error – 如果发生逻辑错误

返回值:

方法返回值的描述。

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

获取面向初学者和高级开发者的深入教程

查看教程

资源

查找开发资源并获得问题解答

查看资源