向 C++ 程式碼新增文件¶

C++ 文件透過 Javadoc 風格註釋提供，並使用 Sphinx、Doxygen 和 Breathe 生成。

文件儲存在副檔名為 .h 的標頭檔案中，以及 .cpp、cu 和 cuh 檔案中。在這些檔案中，#ifndef DOXYGEN_THIS_WILL_BE_SKIPPED 和 #endif 之間的所有內容將從 HTML 輸出中隱藏。向函式新增描述時，請確保 #ifndef 和 #endif 配置正確。

按照以下說明文件化、生成併發布新的 C++ docstring

API 方法按組標籤分組，以便在 Sphinx 中更好地組織。如果目標方法所需的組尚未定義，請在相關標頭檔案頂部附近使用 @defgroup 命令定義它
```
/// @defgroup example-method-group Example Method Group
/// This is a description of the example method group.
```

將 docstring 直接新增到目標方法的宣告上方。至少，請新增以下描述

方法的函式行為
型別引數，由 @tparam 標籤表示
引數，由 @param 標籤表示
返回值，由 @return 標籤表示
可能丟擲的異常（如果適用），由 @throw 標籤表示

其他命令，如 @note、@warning 和 @see 應根據需要新增。

以下是一個 C++ docstring 示例

/// @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);

在 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 docstring 的更多資訊，請參閱此處。

注意

這是一個示例注意。

警告

這是一個示例警告。

模板引數:

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

引數:

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

丟擲:

std::bad_alloc – 如果分配失敗
std::logic_error – 如果發生邏輯錯誤

返回:

方法返回值的描述。

向 C++ 程式碼新增文件¶

文件

教程

資源