| RFC-0183：SDK 程式庫說明文件 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 定義 SDK 中程式庫的參考說明文件規定。 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
摘要
為新增至 SDK 的程式庫定義說明文件規定。
提振精神
大多數 Fuchsia 程式碼都是以原始碼形式提供。雖然 //docs 目錄中偶爾會有總覽文件，或是來源目錄中會有 README.md 檔案，但一般來說，開發人員應參考原始碼，瞭解特定程式庫提供的內容和使用方式。
這種做法無法擴展到作業系統及其眾多支援程式庫的消費者。開發人員希望能夠參考網頁，瞭解一般總覽和個別函式的低階用法。
利害關係人
協助人員：neelsa@google.com
審查人員：mangini@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 會定義產生、格式化及維護程式庫參考說明文件的標準。
FIDL 參考文件仍會使用 fidldoc 基礎架構產生。
實作
從接受這項 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 說明文件標準一般有以下幾項。