添加 C++ 代码文档

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

文档保存在扩展名为 .h 的头文件中，以及 .cpp、cu 和 cuh 文件中。在这些文件中，#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://www.doxygen.nl/manual/commands.html#cmdlink">here</a>.
   template <typename T, std::size_t Alignment>
   int32_t example_method(T param1, float param2);
   

3. 在 Sphinx 文档方面，向相应的 .rst 文件添加 doxygengroup 指令。如果相应头文件的 .rst 文件不存在，请创建一个与头文件同名的文件。使用以上示例

   .. doxygengroup:: example-method-group
     :content-only:
   

4. 确保 .rst 文件包含在 index.rst 中的 toctree 中（例如 FBGEMM_GPU C++ API）。

5. C++ 源代码头文件需要位于 Doxygen.ini 中 INPUT 参数列出的目录之一中。通常情况下，这已经处理好了，但如果它位于未列出的目录中，请确保将目录路径附加到该参数中。

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 文档字符串的更多信息，请参阅 此处。

注意

这是一个示例注释。

警告

这是一个示例警告。

模板参数：

• T – T 的描述

• Alignment – Alignment 值的描述

参数：

• param1 – param1 的描述

• param2 – param2 的描述

抛出：

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

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

返回值：

方法返回值的描述。