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

RFC-0043：說明文件註解格式
狀態	已接受
領域	FIDL
說明	此 FTP 將統一用於撰寫說明文件註解的單一格式。透過產生 API 說明文件的其他人類可讀格式和機器可取用的格式 (例如例如 HTML、Markdown)。
作者	jeremymanson@google.com
提交日期 (年-月-日)	2019-05-06
審查日期 (年-月-日)	2019-05-30

摘要

這個 RFC 針對編寫說明文件的單一格式標準化 留言。 產生 API 說明文件的工具可使用這個格式。 其他人類可讀格式和機器使用的格式 (例如例如 HTML、Markdown)。

提振精神

我們目前提供的 API 說明文件評分量表 有哪些 FIDL 程式碼需要記錄，包括參數 傳回值以及錯誤 我們也鼓勵開發人員提供 API 使用範例。 不過，我們尚未給開發人員明確表示 FIDL API 說明文件中的功能。

隨著 fidldoc 工具問世，讓開發人員在提供資訊時 開發人員在留言中表達格式 撰寫註解的開發人員應知道該如何設定清單格式 。 他們也必須瞭解如何指出某項內容是傳回值或 參數，以便在輸出內容中正確顯示。

設計

重點摘要：我們希望能在註解中使用 Markdown。 當然，魔鬼總是詳細記錄在細節上。

此 RFC 修改了 API 說明文件評分量表和我們使用的工具 來處理 FIDL API 說明文件。 不會影響一組合法 FIDL 的語言。 保持不變

為什麼要使用 Markdown？

文件註解的解決方案空間可分為兩個部分： 「開發自己的解決方案」並且「使用現有的解決方案」。 我們認為 FIDL 不會是足夠的生態系統 另外開發了一種獨立的註解語法標準 使用現有解決方案，開發人員將能充分運用 外部文件和工具 (可能也包含 相關知識)。 此外，使用現有的解決方案或許可以節省開發時間。

如果我們承諾使用現有的解決方案，就必須選擇一種。 有幾種特定語言適用的解決方案需要擴充 (例如 javadoc 和 Python doc 字串)。 此外，我們也提供一般用途的解決方案 (例如LaTeX、RST、Markdown)。

我們相信 Markdown 是最好的選擇。 有別於程式語言的解決方案，您可以在 允許 Markdown 整合到新語言。 Markdown 也廣為使用及開發人員，可幫助開發人員瞭解這項工具 。 最後，將數種語言 (例如Rust 和 Kotlin) 會標準化 所以使用 Markdown 編寫的語法，就會開始取代現有字詞 以其他語言提供解決方案 (例如 LLVM 將 從 RST 遷移至 Markdown)。

Markdown 是什麼意思？

Markdown 的各種導入方式略有不同 行為 數量不限。 我們選擇 CommonMark，因為這正是我們找到標準的最接近結果之一。 適用於工具需要同時指定 CommonMark 和其他 ID 的開發人員 實作 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，持續回報錯誤。

其他 FIDL 語言元素的連結 (具有相關說明文件) 可以藉由新增 [`link-target`] 來建立 (或已記錄的實體)。 舉例來說，[`fidl.io/NodeInfo`] 會連結至特定程式庫的說明文件。 這些解決規則如下：

1. 首先，系統會檢查巢狀元素。 如果您要記錄 struct Object，且其中包含成員 event，就可以稱為 [`event`]。
2. 接著，如果元素與記錄元素位於相同範圍層級，就會產生 項目 舉例來說，如果您要記錄通訊協定方法 foo()， 同一個通訊協定包含 bar() 方法，您可以透過 [`bar`] 稱謂。
3. 接著，假如內部 IP 位址 其涵蓋範圍 舉例來說，如果您要記錄通訊協定方法 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 的 Javadoc。 開發人員覺得這很麻煩。 其他語言則使用 RST。 但這越來越不受歡迎；開發人員只是 很熟悉 Markdown 值得注意的是，LLVM 專案已從 RST 遷移至 Markdown。

我們考慮使用不同的 Markdown 變化版本。 我們決定使用 CommonMark 最具優勢， 標準化 需要自家程式碼在其他 Markdown 轉譯系統中運作的開發人員 撰寫文件註解時， 應同時符合 CommonMark 與 他們的目標系統

我們考慮沒有發明新的語法來連結有記錄的實體。 考量的替代方案如下：

• 自動偵測。 已在其他情境下具備自動偵測機制的經驗 讓他們難以偵測出開發人員預期的目的 此外，自動偵測功能還可防止工具 指出連結有誤 因此，我們會將自動偵測功能延後到未來日期。
• 使用現有語法。 這與自動偵測的問題相同，但症狀 較糟糕 如果要使用 fuchsia.io/NodeInfo 做為語法，那麼 卻找不到連結，而是透過 ， 我們希望工具能偵測無效連結 備用行為

我們日後應該考慮的項目，但不在這 RFC，包含：

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

既有藝術品和參考資料

本提案主要受到 Rust 說明文件樣式的影響 以及 Kotlin