| RFC-0055：說明文件註解 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 記錄 FIDL。 |
| 作者 | |
| 提交日期 (年/月) | 2018-07-31 |
| 審查日期 (年/月) | 2018-08-20 |
摘要
記錄 FIDL。
與其他 RFC 的關係
本 RFC 修訂者如下：
提振精神
優質說明文件不僅是拓展團隊規模的重要一環，記錄我們的 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);
}
這會脫糖處理：
[Doc="Sent when an adapter with the given |identifier| has been\n removed from the system\n"]
說明文件註解內容
文件註解主要是任意形式的文字。任何特定的格式樣式皆取決於作者、團隊或日後的樣式指南。唯一新增的基本 ID 是 ID 標記，目前提議以直立線 (|) 做為本機 ID。不合格 ID 的範圍僅限於已附加該屬性的物件底下的成員。完整 ID 可用於參照目前範圍以外的物件 (例如：|fuchsia.bluetooth.ErrorCode|)。
最後，如果缺少任何 ID，fidldoc 文件產生應該就會失敗，但該屬性仍會納入並傳遞至語言繫結。這麼做可避免說明文件輪替。由於執行這些步驟是刻意避免將 ID 新增至 IR 或剖析步驟的一部分。擷取 ID 屬於說明文件工具 (fidldoc)。文件產生作業應新增為標準偵錯版本的必要部分，若無法成功產生說明文件，整體建構作業也會失敗。
其他工具
系統應該將名為 fidldoc 的標準工具新增至工具目錄。Fidldoc 會在使用 FIDL JSON IR 後產生 Markdown。Markdown 是目前與其他一類語言說明文件工具搭配使用的格式。
其他
傳輸格式不受這些異動影響。語言繫結選擇如何顯示文件字串或顯示文件字串的方式，會做為各自社群的實作詳細資料，或可能做為其他 FTP 的實作詳細資料。
樣式指南應修訂為優先使用 ///，而非文件屬性，不過除此之外，請勿任意保留。
說明文件與範例
三則註解是表示說明文件註解的一種常見方式，對瞭解語言語句的障礙來說不應太大。使用三組註解的範例應新增到現有說明文件，並解釋如何使用屬性註解。
使用者使用這項功能的主要方式是產生的輸出內容，
這項功能回溯相容於所有近期的 fidlc 編譯器。雖然三組註解語法糖不會出現新功能，但這些新功能不會破壞舊版編譯器。
文件屬性註解功能不必變更任何語言即可運作。
效能
除非 JSON IR 大小稍微增加，否則預計不會發生效能變化。我們也會在編譯期間產生說明文件，稍微減慢建構速度。
安全性
不適用
測試
不適用
缺點、替代方案和未知
需要採用一般協議和使用的特定語法。語法可以很容易地修改 (也可以騎腳踏車)，同時改變提案的核心概念。
與 fidldoc 相關的可能替代方案為編譯器自行產生說明文件。您也可以採用現有的後端產生器方法進行這項作業。所產生說明文件的輸出格式也適用於討論。
另一個替代方法是在 AST 中將說明文件註解當做第一類別引用。雖然這項策略完全沒有缺點，但會以屬性建立模型時，無法獲得一些擴充性。我們有時會想加入說明文件工具和屬性樣式的額外資訊，而不用做出破壞性變更。例如，我們可能會允許指定留言的 Markdown 語言。這樣就能將用於產生說明文件的所有資訊儲存在相同輸出 (屬性) 中。這樣做也會強制執行良好的規律，讓系統以相同的位置限制剖析文件註解和屬性。
先前的圖片和參考資料
大多數的語言都有說明文件工具。上述程式碼取自先前的 dartdoc、rustdoc 和 javadoc (大部分非實用做法)