本頁面由 Cloud Translation API 翻譯而成。

RFC-0043：說明文件註解格式

RFC-0043：說明文件註解格式
狀態	已接受
區域	FIDL
說明	這個 FTP 統一撰寫文件註解的單一格式。若工具能夠以其他人類可讀的格式和機器消耗格式產生 API 說明文件 (例如。
作者	jeremymanson@google.com
提交日期 (年/月)	2019-05-06
審查日期 (年/月)	2019-05-30

編輯此 RFC

編輯 RFC 中繼資料

摘要

這個 RFC 標準化用來撰寫說明文件註解的單一格式。若工具能夠以其他人類可讀的格式和機器消耗格式產生 API 說明文件 (例如。

提振精神

我們目前提供 API 說明文件評分量表，當中說明瞭需要記錄的 FIDL 程式碼哪些方面，包括參數、傳回值和錯誤。此外，我們也鼓勵開發人員提供 API 使用情況的範例。然而，我們並未在 FIDL API 說明文件中讓開發人員清楚表達這些功能。

隨著 fidldoc 工具的問世，提供開發人員在註解中表達格式變得比以往更重要。例如，撰寫註解的開發人員應該知道如何在輸出中設定清單格式。他們也必須知道如何指出內容是回傳值或參數，才能正確顯示在輸出內容中。

設計

重點摘要：我們想針對註解使用 Markdown。當然，魔鬼的本質就在這些。

這個 RFC 會修改 API 說明文件評分量表，以及用於處理 FIDL API 說明文件的工具。這項政策不會影響 FIDL 語言，因為法律 FIDL 的組合保持不變。

為什麼要使用 Markdown？

文件註解的解決方案空間可分為兩個部分：「開發自己的解決方案」和「使用現有的解決方案」。我們認為 FIDL 並沒有足夠的規模，可以維護一個獨立的留言語法標準。藉由使用現有解決方案，開發人員將能利用外部說明文件和工具 (可能包括現有的知識)。此外，使用現有解決方案可節省開發時間。

如果我們承諾使用現有解決方案，就必須選擇一種解決方案。有一些語言特定的解決方案可以使用擴充 (例如 javadoc 和 Python 文件字串)。另外，也有一般用途的解決方案 (例如LaTeX、RST、Markdown)。

我們認為 Markdown 是最好的選擇。有別於語言專用的解決方案，有許多工具可讓 Markdown 整合至新語言。Markdown 也廣為使用並由開發人員理解，以 GitHub 為例，這項工具可用於提供說明文件。最後，有多種語言 (例如Rust 和 Kotlin) 正針對 Markdown 進行語法標準化，並開始取代其他語言的現有解決方案 (例如 LLVM 即將從 RST 遷移至 Markdown)。

Markdown 是什麼意思？

Markdown 有各種導入方式，這些行為的行為會略有不同。任意數量都是合理選擇。我們選擇 CommonMark，因為這是最接近標準的格式。如果開發人員的工具需要同時指定 CommonMark 和另一項標記實作，請盡可能讓說明文件與這兩種實作項目相容。

Markdown 無法擴充，也無法協助您表達語言元素。我們加入了可由 fidldoc (和其他使用工具的 API 文件) 處理的特殊用途 Markdown 擴充功能。

文件註解會以 Markdown 編寫，並位於其記錄的元素之前。其中包含說明，後面可選擇參數、錯誤和「查看」(表示讀取器應查看參照的 API 以取得更多資訊)。

參數和錯誤

請求參數應妥善記錄：

* request `paramname` Description of parameter

回應參數應妥善記錄：

* response `paramname` Description of parameter

我們也會將 param 和 return (或 in 和 out) 視為關鍵字，而不是 request 和 response。

如果方法沒有使用同一個 ID 做為要求和回應的參數，則 request 和 response 為選用字詞。

沒有參數值 (Foo() -> ()) 傳回的方法可以使用 response，而沒有對應參數的說明文件。

錯誤子句應記載：

* error Description of error values

完整名稱

完整名稱的格式為：

<library>/<top level declaration>.<member>

這可以讓您識別所有成員，因為沒有超載。

目前，序數雜湊是以 <library>.<top level declaration>/<member> 格式的名稱為基礎 (請參閱 RFC-0020)，fidlc 會使用 <library>.<top level declaration>/<member> 格式回報錯誤。我們致力於針對上述「不明確」的格式達成共識。我們將修訂「RFC-0029：增加方法序數」，以使用 <library>/<top level declaration>.<member> 做為經過雜湊處理的名稱，並修改 fidlc 以一致地回報錯誤。

您可以新增 [「link-target」]，連結至其他具有相關說明文件 (或已記錄實體) 的其他 FIDL 語言元素連結。例如，[`fidl.io/NodeInfo`] 可透過上述程式庫的文件連結。解決規則如下：

首先，系統會檢查巢狀元素。如果您要記錄 struct Object 且包含成員 event，可以稱為 [`event`]。
接下來，系統會檢查與所記錄元素位於相同範圍層級的元素。舉例來說，如果您要記錄通訊協定方法 foo()，且同一個通訊協定包含 bar() 方法，就可以將其稱為 [`bar`]。
接下來，檢查此範圍中的元素 (如果有) 就要檢查。舉例來說，如果您正在記錄通訊協定方法 foo()，且同一資料庫中有另一個名為 Info 的通訊協定，您可以藉由說 [`Info`] 參照此通訊協定 (及其元素)。
3 會連續封閉式範圍，直到位於頂層範圍為止。如果您正在記錄通訊協定方法 foo()，並且編寫了 [`fuchsia.io/NodeInfo`]，則其會參照聯集 fuchsia.io/NodeInfo。

完整名稱格式為 <library>/<top level declaration>.<member>，詳情請參閱上方說明。

如果是其他連結捷徑，你可以指定連結目標，例如：

[fuchsia-concepts]: https://fuchsia.dev/fuchsia-src/concepts

該行不會顯示在工具輸出中。

如果工具在執行階段知道指定 FIDL 目標類型，就不需要指定位置。舉例來說，fuchsia.sys/ComponentController 和 fuchsia.sys/EnvironmentController 的文件可能已在產生同一項工具叫用時產生。這項工具會知道這些連結之間的關係。

開發人員也可以使用下列程式碼，指出特定 API 有相關的 API：

* see [`fidl.io`]

視情況而定。

導入策略

實作內容包括將其新增至 FIDL 評分量表、公開發布，以及將特殊註解整合至 fidldoc 工具。我們也可以將 fidldoc 語法的 Lint 檢查功能新增至 fidl-lint 工具或個別工具。

說明文件與範例

完整範例如下所示。請注意，這個 API 目前看起來不像這樣，狀態已變更為錯誤，以示意圖。

library fuchsia.io;

protocol File {
    /// Acquires a [`fuchsia.mem/Buffer`] representing this file, if
    /// there is one, with the requested access rights.
    ///
    /// ## Rights
    ///
    /// This method requires the following rights:
    ///
    /// * [`OPEN_RIGHT_WRITABLE`] if `flags` includes
    ///   [`VMO_FLAG_WRITE`].
    /// * [`OPEN_RIGHT_READABLE`] if `flags` includes
    ///   [`VMO_FLAG_READ`] or [`VMO_FLAG_EXEC`].
    ///
    /// + request `flags` a bit field composing any of
    ///   `VMO_FLAG_READ`, `VMO_FLAG_WRITE`, or `VMO_FLAG_EXEC`.
    /// - response `buffer` the requested [`fuchsia.mem/Buffer`], or
    ///     null if there was an error, or the buffer does not exist.
    /// * error a `zx.status` value indicating success or failure.
    /// * see [Filesystem architecture][fs-arch] for further details.
    ///
    /// [fs-arch]: https://fuchsia.dev/fuchsia-src/concepts/filesystems/filesystems
    GetBuffer(uint32 flags) ->
        (fuchsia.mem.Buffer? buffer) error zx.status;
};

請注意，依照慣例，您只需要將第一個參照連結至特定文件註解中的元素。上述 VMO_FLAG_READ 的第一個參照是連結狀態，第二個參照則沒有。

回溯相容性

沒有重大的回溯相容性問題。目前的文件使用 C++ 樣式 |param| 標記法來指出參數和傳回值。但修改方式比較簡單。

效能

這會影響開發人員的速度，使其類型更多，但也有助於瞭解詳情。

缺點、替代方案和未知

這裡假設格式比不使用格式還要好。因此，您有一些缺點

替代項目可能包含其他 API 文件格式。Java 使用 Javadoc，這非常冗長，需仰賴內嵌 HTML。開發人員認為這項服務相當棘手。其他語言則使用 RST。但是，這越來越不受歡迎，開發人員只是對 Markdown 更熟悉了。值得注意的是，LLVM 專案正從 RST 遷移至 Markdown。

我們考慮使用不同版本的 Markdown。我們決定使用 CommonMark，因為它是最佳指定且經過標準化處理的。如果開發人員需要自己的程式碼在其他 Markdown 轉譯系統中運作，就必須嘗試撰寫文件註解，同時符合 CommonMark 以及他們指定的系統的要求。

我們尚未設計用來連結記錄實體的新語法。以下是考慮的替代方案：

自動偵測。在其他情況下，如果具備自動偵測機制的經驗，就會發現這些機制很少偵測到開發人員的預期行為。此外，自動偵測功能也會防止工具指明連結錯誤。因此，我們會延後自動偵測功能，直到未來的日期為止。
使用現有的語法。這種情況與自動偵測功能相同，但症狀略有缺陷。如果將 fuchsia.io/NodeInfo 設為語法，如果拼寫有誤，連結就不會顯示，因此只會取得程式碼字型。我們希望工具能偵測無效連結，而非採用備用行為。

我們日後應納入考量，但超出此 RFC 範圍的項目，包括：

將圖片或流程圖嵌入生成文件的方法。
將範例嵌入文件中自動檢查的方法。

先前的圖片和參考資料

本提案大幅影響了 Rust 和 Kotlin 的說明文件樣式。