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 的說明文件就是使用 Markdown 撰寫。最後，部分語言 (例如Rust 和 Kotlin) 正在將 Markdown 標準化為語法，並開始取代其他語言的現有解決方案 (例如 LLVM 即將從 RST 遷移至 Markdown)。

什麼是 Markdown？

Markdown 有多種實作方式，行為略有不同。任何數量都是合理的選擇。 我們選擇 CommonMark，因為這是最接近標準的格式。 如果開發人員的工具需要同時以 CommonMark 和其他 Markdown 實作為目標，建議盡可能讓文件與兩者相容。

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>

由於沒有多載，因此這會是任何成員的專屬 ID。

目前，序數雜湊是以 <library>.<top level declaration>/<member> 形式的名稱為準 (請參閱 RFC-0020)，而 fidlc 會使用 <library>.<top level declaration>/<member> 形式回報錯誤。我們打算將這些格式統一為上述明確格式。 我們會修改 RFC-0029：增加方法序數，使用 <library>/<top level declaration>.<member> 做為雜湊名稱，並修改 fidlc，以便一致地回報錯誤。

如要連結至其他有相關說明文件的 FIDL 語言元素 (或已記錄的實體)，請新增 [`link-target`]。舉例來說，[`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 的文件樣式影響。