| RFC-0183：SDK 程式庫說明文件 | |
|---|---|
| 狀態 | 已接受 |
| 領域 |
|
| 說明 | 為 SDK 中的程式庫定義參考說明文件。 |
| 問題 | |
| 更小鳥 | |
| 作者 | |
| 審查人員 | |
摘要
為新增至 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、tmandclaine@google.com、theosiulk@google.com theosiulk@google.com
社交：不適用
設計
這個 RFC 定義用來記錄 SDK 程式庫的規則和位置：
- 新增至公開或合作夥伴 SDK 的新程式庫必須具備公開 (或合作夥伴 SDK 受合作夥伴限制) 參考說明文件。
- 這份說明文件應專為 SDK 使用者所設計，但如果這些概念清楚明確，可能會參照 fuchsia.git-only 概念。
- 說明文件必須足以讓開發人員使用這些程式庫，而不必查看原始碼或標頭檔案。
- 負責程式庫程式碼的開發人員將負責產生及維護參照內容。
- 如果程式庫的語言支援，則應由 //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++ 說明文件工具，Fchsia 團隊成員也為 Clang 中的 clang-doc 做出貢獻。
FIDL 採用 RFC-0043 和 RFC-0055 定義的現有標準和格式。
Fuchsia Rust 團隊負責維護 Fuchsia Rust 程式庫的參考資訊。在 SDK 支援 Rust 之前，這些標準會由獨立網站代管。
包括一般的 Fuchsia 說明文件標準。