為 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://doxygen.dev.org.tw/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.rst 中的 toctree 中 (例如 FBGEMM_GPU C++ API)。

5. C++ 原始碼標頭檔需要位於 Doxygen.ini 中 INPUT 參數中列出的其中一個目錄中。一般而言，這已處理完畢，但如果它位於未列出的目錄中，請務必將目錄路徑附加至參數。

6. 透過在本機使用 建置文件 建置文件或提交 Netlify 預覽的 PR 來驗證變更。

---

上述 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 – 如果發生邏輯錯誤

傳回:

方法傳回值的描述。