| RFC-0055：說明文件註解 | |
|---|---|
| 狀態 | 已接受 |
| 領域 |
|
| 說明 | 記錄 FIDL。 |
| 作者 | |
| 提交日期 (年-月-日) | 2018-07-31 |
| 審查日期 (年-月-日) | 2018-08-20 |
摘要
記錄 FIDL。
與其他 RFC 的關係
此 RFC 已修訂者：
提振精神
優質說明文件不僅是拓展團隊規模的重要一環 的 API 是定義穩定的 API 的重要一環Fuchsia API 為 主要是在 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 的限定範圍僅限於物件之下的成員 屬性也會一併附加可使用完整的識別碼 (例如：|fuchsia.bluetooth.ErrorCode|) 參照位於目前範圍外的物件 範圍。
最終，如果 缺少 ID，但仍會加入並傳送屬性 轉換為語言繫結這可避免說明文件輪替。新增 事件 ID 或剖析步驟的一部分 簡化這些步驟擷取屬於 說明文件工具 (fidldoc)。文件產生作業應新增為 標準偵錯版本的必要部分，且整體建構會失敗 未成功產生說明文件
其他工具
您必須將標準工具 (稱為 fidldoc) 新增至工具目錄。Fidldoc 在使用 FIDL JSON IR 後會產生 Markdown。Markdown 是最新內容 與其他一流語言說明文件搭配使用的格式 工具
其他
電匯格式不受這些異動影響。語言繫結的選擇方式 表面 docstrings，但如果顯示這些 docString，則會保留實作詳細資料 或可能為其他 FTP
樣式指南應修訂，優先採用 /// 而非 doc 屬性，但
否則都藏著孤身
說明文件和範例
三註解是相對常見的方式表示文件註解方式 而不是理解 fidl 語言的阻礙。範例 應將三者註解新增至現有說明文件 說明如何使用屬性註解的說明。
使用者使用這項功能的主要方式 輸出內容
回溯相容性 這項功能已與所有裝置回溯相容 近期的 fidlc 編譯器雖然 三段註解語法糖，也不會破壞較早的編譯器。
文件屬性註解無需變更任何語言即可運作。
成效
預期不會有任何效能變化，除了 JSON IR 中的小幅增加之外 大小我們也會在編譯期間產生說明文件，進而拖慢速度 少量的容器
安全性
不適用
測試
不適用
缺點、替代方案和未知
您必須對方法和所用特定語法進行一般協議 應用方式。語法很容易修改 (且可修改)，但確實能改變 提案的核心構想
若是 fidldoc 可能的替代方案，就是編譯器 說明文件本身您也可以使用現有的後端 產生何種方法生成文件的輸出格式可能 也歡迎大家討論
另一個替代方案是將說明文件註解顯示為優先類別 公民在澳洲首都特區雖然這個策略沒有任何缺點 無法像以屬性的形式建立模型日後 我們可以提供更多說明文件工具和 屬性樣式可讓您在不破壞變更的情況下進行。舉例來說，我們 可能想要指定註解的 Markdown 語言。這會導致 則請將產生相關文件的所有資訊 輸出的值 (屬性)這套系統還能強制定期提供文件 剖析時，系統會將具有相同刊登位置限制的註解和屬性剖析 使用這個層即可
既有藝術品和參考資料
大多數語言都有文件工具。從過往的飛鏢靶 rustdoc 和 javadoc (主要是在避免的做法)