RFC-0055：說明文件註解

摘要

記錄 FIDL。

與其他 RFC 的關係

本 RFC 修訂內容如下：

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

提振精神

除了是擴大團隊的重要一環，說明文件也是定義穩定 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);
}

這會將糖分解為：

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

說明文件註解內容

文件註解主要是自由文字。任何特定的格式風格都由作者、團隊或日後的樣式指南決定。新增的唯一原始元素是 ID 標記，目前建議使用管道符號 (|) 包裝本地 ID。未經修飾的 ID 會將範圍限定為屬性所附加的物件底下的成員。您可以使用完整的 ID (例如 |fuchsia.bluetooth.ErrorCode|)，參照目前範圍以外的物件。

最後，如果缺少任何 ID，fidldoc 說明文件產生作業應會失敗，但屬性仍會納入並傳遞至語言繫結。這麼做可避免說明文件過時。我們刻意避免在 IR 中加入 ID，或在剖析步驟中加入 ID，因為這會使這些步驟變得複雜。擷取 ID 屬於說明文件工具 (fidldoc) 的範疇。您應將文件產生作業新增為標準偵錯版本的必要部分，如果無法順利產生文件，整體建構作業就會失敗。

其他工具

您應該將名為 fidldoc 的標準工具新增至工具目錄。Fidldoc 會在使用 FIDL JSON IR 後產生 Markdown。Markdown 是我們目前用於其他第一級語言說明文件工具的格式。

其他

Wire 格式不會受到這些變更的影響。語言繫結如何選擇顯示 docstring，或是否顯示 docstring，則留給各自的社群，或可能做為額外的 FTP。

您應修改樣式指南，讓 /// 優先於 doc 屬性，但其他部分則保持不變。

說明文件和範例

三重註解是表示文件註解的常見方式，不應成為理解 fidl 語言的重大障礙。應在現有文件中加入使用三重註解的範例，並說明如何使用屬性註解。

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

回溯相容性：這項功能已與所有先前最新的 fidlc 編譯器回溯相容。雖然三重註解語法糖不會提供新功能，但不會影響先前的編譯器。

文件屬性註解會在任何語言變更下運作。

成效

除了 JSON IR 大小略微增加外，效能不會有任何變化。我們也會在編譯時產生文件，這會稍微減緩建構作業。

安全性

不適用

測試

不適用

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

採用者必須同意採用的做法和使用的特定語法。語法很容易修改 (並且可用於測試)，而且不會變更提案的核心概念。

針對 fidldoc 的潛在替代方案是，編譯器會自行產生說明文件。您也可以使用現有的後端產生器方法。我們也歡迎討論產生說明文件的輸出格式。

另一種做法是將說明文件註解視為 AST 中的一級元素。雖然這項策略沒有任何實際缺點，但您會失去將其模擬為屬性所帶來的某些可擴充性優勢。有一天，我們可能會想為我們的文件工具新增額外資訊，而屬性樣式可讓我們在不破壞變更的情況下做到這點。舉例來說，我們可能會允許指定註解的 Markdown 語言。這樣一來，您就能在同一個輸出內容 (屬性) 中保留產生文件的所有資訊。它還會強制執行規則，讓具有類似刊登位置限制的文件註解和屬性以相同方式解析。

既有技術與參考資料

大多數語言都有說明文件工具。這項做法參考了先前 Dartdoc、Rustdoc 和 Javadoc 的做法 (主要是不該做的部分)