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

摘要

這份 RFC 將統一說明文件註解的格式。使用此格式的工具可產生其他人類可讀且機器可讀取的格式 (例如HTML、Markdown)。

提振精神

我們目前有一份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 實作，建議盡可能讓文件與兩者相容。

Markdown 無法擴充，因此無法用於表達語言元素。我們新增了 Markdown 的特殊用途擴充功能，可由 fidldoc (以及其他 API 文件使用工具) 處理。

文件註解是以 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`] 會連結至該程式庫的說明文件。解析規則如下：

1. 首先，系統會檢查巢狀元素。如果您正在記錄 struct Object，且其中包含成員 event，您可以將其稱為 [`event`]。
2. 接著，系統會檢查與已記錄元素相同範圍層級的元素。舉例來說，如果您正在記錄通訊協定方法 foo()，而同一個通訊協定包含方法 bar()，您可以將其稱為 [`bar`]。
3. 接著，如果有包函範圍，系統會檢查包函範圍的元素。舉例來說，如果您正在記錄通訊協定方法 foo()，而同一個程式庫中還有另一個名為 Info 的通訊協定，您可以使用 [`Info`] 來參照該通訊協定 (及其元素)。
4. 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：

* 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 說明文件樣式的影響。