RFC-0055：說明文件註解

摘要

記錄 FIDL。

與其他 RFC 的關係

這項 RFC 的修訂內容如下：

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

提振精神

優質說明文件不僅是擴大規模團隊的重要環節，記錄 API 也是定義穩定 API 的重要環節。Fuchsia API 主要以 FIDL 實作，大量說明文件都留在註解中，難以呈現。更糟的是，人們經常會查看產生的繫結，瞭解如何使用介面。這項提案是 FIDL 語言和介面全面文件策略的第一步。

設計

系統會提議兩項 FIDL 來源語言變更。標準 Doc 屬性 和語法糖，可提升撰寫文件的便利性。

文件屬性

任意屬性是 FIDL 語言中已支援的元件。 標準化 Doc 屬性適用於生成格式化文件的工具。以屬性做為文件工具的基礎，也能在不造成重大變更的情況下，為格式化輸出內容新增其他選項。

[Discoverable, Doc = "Primary Bluetooth control service to access bluetooth"]
interface Control {
  ...
  [Doc = "Sets the public Bluetooth |name| for this device"]
  10: SetName(string? name) -> (fuchsia.bluetooth.Status status);
}

目前每個語言元素只能有一個 Doc 屬性。因此所有文字都必須放在屬性大括號中，可能會導致行過長。

語法糖

為解決使用屬性時的人體工學問題，我們建議使用語法糖層。

這項變更涉及 FIDL 語言規格的小幅變動。目前在 FIDL 詞彙化期間，系統會忽略註解。這個 FTP 並未說明如何將一般註解新增至 AST，僅說明如何新增文件註解。

屬性是 FIDL 語言表達附加至結構體的中繼資料概念的主要方式。將文件註解視為這個特殊案例，可簡化 IR 中繼資料的取用程序。

建議的文法修改內容位於 FTP 的附錄中，但主要涉及新增一項規則，以及稍微重新排序規則。

documentation-comment = "///", STRING-LITERAL, "\n"

interface Control {
  /// Sent when an adapter with the given |identifier| has been
  /// removed from the system.
  10102: -> OnAdapterRemoved(string identifier);
}

這會將「de-sugar」設為：

[Doc="Sent when an adapter with the given |identifier| has been\n removed from the system\n"]

說明文件註解內容

文件註解主要為自由文字。格式的具體樣式取決於作者、團隊或日後的樣式指南。新增的唯一基本元素是 ID 標記，目前建議使用管道 (|) 包住本機 ID。不合格的 ID 會限定在屬性所附加物件下方的成員。完整識別碼可用於參照目前範圍外的物件 (例如 |fuchsia.bluetooth.ErrorCode|)。

如果缺少任何 ID，最終應會導致 fidldoc 文件生成失敗，但屬性仍會納入並傳遞至語言繫結。這有助於避免文件過時。為避免這些步驟變得複雜，我們刻意不將 ID 新增至 IR 或剖析步驟中。擷取 ID 屬於文件工具 (fidldoc) 的範疇。文件生成應做為標準偵錯建構的必要部分，如果文件未成功生成，整體建構應會失敗。

其他工具

標準工具 (稱為 fidldoc) 應新增至工具目錄。Fidldoc 會在耗用 FIDL JSON IR 後產生 Markdown。Markdown 是我們目前使用的格式，適用於其他一流語言的文件工具。

其他

Wire 格式不受這些異動影響。語言繫結選擇如何顯示文件字串，或是否顯示文件字串，則留待各社群或潛在的額外 FTP 實作詳細資料。

應修訂樣式指南，將 /// 設為優先於文件屬性，但其他部分則維持不變。

說明文件和範例

三斜線註解是標示文件註解的常見方式，應該不會對瞭解 FIDL 語言造成太大障礙。範例 使用三斜線註解應新增至現有文件，並說明如何使用屬性註解。

使用者主要會透過生成的輸出內容使用這項功能。

回溯相容性：這項功能已與所有近期的 fidlc 編譯器回溯相容。雖然三斜線註解語法糖不會有新功能，但不會中斷先前的編譯器。

文件屬性註解不會受到語言變更影響。

效能

除了 JSON IR 大小會略為增加，預計不會有任何成效變化。我們也會在編譯時產生文件，這會稍微減緩建構速度。

安全性

不適用

測試

不適用

缺點、替代方案和未知事項

如要採用這項做法，必須先就做法和使用的特定語法達成一般共識。語法很容易修改 (和討論)，而且會改變提案的核心概念。

就 fidldoc 而言，可能的替代方案是編譯器自行產生說明文件。此外，您也可以使用現有的後端產生器方法。產生的說明文件輸出格式也可能需要討論。

另一種替代做法是在 AST 中將文件註解表示為一等公民。雖然這項策略沒有任何實際缺點，但您會失去將其做為屬性建模時的一些擴充性優勢。我們日後可能會想為文件工具新增其他資訊，而屬性樣式可讓您達成這個目標，不必進行重大變更。舉例來說，我們可能想允許指定註解的 Markdown 語言。這樣一來，系統就會將產生文件所需的所有資訊保留在同一個輸出內容 (屬性) 中。此外，這項功能還會強制執行良好的規律性，以相同方式剖析具有類似位置限制的文件註解和屬性。

既有技術和參考資料

大多數語言都有文件工具。這項功能參考了 dartdoc、rustdoc 和 javadoc 的先前技術 (主要是不要做什麼)