| RFC-0183：SDK 程式庫說明文件 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 定義 SDK 中程式庫參考文件的規定。 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
摘要
定義新增至 SDK 的程式庫說明文件規定。
提振精神
大多數 Fuchsia 程式碼都是以原始碼形式提供。雖然 //docs 目錄中偶爾會有概略說明文件，來源目錄中也有 README.md 檔案，但開發人員通常會參考原始碼，瞭解特定程式庫提供的內容和使用方式。
這種做法無法擴展至作業系統的使用者，以及其所有支援程式庫。開發人員希望能參考網頁，瞭解整體概況和個別函式的較低層級用法。
相關人員
協助人員：neelsa@google.com
審查者：mangi@google.com、mkearney@google.com、hjfreyer@google.com、ccherubino@google.com
諮詢對象：sebmarchand@google.com、surajmahotra@google.com、dschuyler@google.com、jeremymanson@google.com、yifeit@google.com、computerdruid@google.com、nickvander@google.com、tmandry@google.com、theosiu@google.com、wilkinsonclay@google.com、kyol@google.com、pineapple@google.com
社交化：不適用
設計
本 RFC 定義了 SDK 程式庫的說明文件規則和位置：
- 新增至公用或合作夥伴 SDK 的程式庫必須提供公開 (或合作夥伴 SDK 的合作夥伴專屬) 參考說明文件。
- 說明文件應以 SDK 使用者為對象，但如果可以清楚識別，則可參照 fuchsia.git 專屬概念。
- 說明文件必須足以讓開發人員使用這些程式庫，而無須查看原始碼或標頭檔案。
- 負責程式庫程式碼的開發人員將負責產生及維護參考內容。
- 如果程式庫的語言支援，則應由 //tools/docsgen 基礎架構產生參考說明文件。如果不支援，開發人員可以選擇格式或技術，只要該格式或技術有在 fuchsia.dev 上放送的路徑即可 (請傳送電子郵件至 api-council@fuchsia.dev，取得最新的建議)。
為了方便說明本文件的用途，「參考文件」是指說明哪些函式和物件存在，以及如何使用這些函式和物件的文件。這份文件假設您對系統有充分的瞭解，也知道程式庫的一般目標為何。這與概覽和教學課程等較高層級文件有所不同。
本 RFC 不定義：
- 總覽和教學課程等高階說明文件的規定。
- 詳細標準，說明優質的程式庫參考資料必須包含哪些內容。
隨著程式庫說明文件的演進，日後的 RFC 將定義產生、格式化及維護程式庫參考說明文件的標準。
我們會繼續使用 fidldoc 基礎架構產生 FIDL 參考文件。
實作
從這個 RFC 通過後開始，程式庫說明文件規則將套用至 SDK 中新增的程式庫。
團隊會逐步為 SDK 中現有的程式庫撰寫文件。這項工作的機制尚未定義。
缺點、替代方案和未知因素
這項規定可能會導致有用的程式庫無法及時加入 SDK。但如果沒有可用的參考資料，可能就無法充分發揮新程式庫的效益。
避免為來源定義格式 (例如原始碼文件註解) 或最終呈現方式 (例如文件內容和組織方式)，可能會導致初始新增內容採用不同的方法。我們日後可能會重新整理這些項目。這項提案旨在避免初始文件工作變得複雜，並讓團隊在決定更詳細的規格前先進行一些實驗。
既有技術與參考資料
其他作業系統供應商會維護網站，為開發人員提供系統程式庫的說明文件。例如：
- Android Automotive 程式庫：Android 上的系統程式庫範例。
- Uniscribe：Microsoft Windows 隨附的國際化程式庫範例。
- ARKit：Apple 提供的系統程式庫範例。
許多程式設計語言都有可從原始碼產生說明文件的工具，例如 Java 的 javadoc 和 Rust 的 rustdoc。Doxygen 是最常用的 C++ 說明文件工具，Fuchsia 團隊成員也曾在 Clang 中提供 clang-doc 的貢獻。
FIDL 已實現 RFC-0043 和 RFC-0055 定義的現有標準和格式。
Fuchsia Rust 團隊會維護 Fuchsia Rust 程式庫的參考資訊。在 SDK 支援 Rust 之前，這些檔案會託管在個別網站上。
請參閱一般 Fuchsia 說明文件標準。