RFC-0183：SDK 程式庫說明文件

RFC-0183：SDK 程式庫說明文件
狀態已接受
區域
  • 開發人員
說明

針對 SDK 中的程式庫定義參考說明文件的相關規定。
問題
變更
  • 701555
作者
審查人員

編輯此 RFC

編輯 RFC 中繼資料

摘要

為已新增至 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、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 中已有的程式庫。這個工作的機制尚未定義。

缺點、替代方案和未知

這項規定可能導致應用程式停止加入有用的程式庫。不過，如果沒有可用參照，可能無法實現新程式庫的完整優勢。

避免為來源定義格式 (例如原始碼文件註解) 或最終呈現方式 (例如說明文件包含的內容和規劃方式)，可能會在初始新增項目時選擇不同的方式。我們日後可能會需要重新安排這些內容。本提案的設計旨在避免複雜的初始說明文件工作，並讓團隊在決定更詳細的規定前，能提供一些經驗。

先前的圖片和參考資料

其他作業系統供應商負責維護網站，其中記錄了開發人員專用的系統程式庫。例如：

許多程式設計語言都有工具可從原始碼產生說明文件，例如 Java 的 javadoc 和 Rust 的 rustdoc。Doxygen 是最常用的 C++ 說明文件工具，Fuchsia 團隊成員也在 Clang 中對 clang-doc 做出貢獻。

FIDL 具有 RFC-0043 和 RFC-0055 所定義的現有標準和格式。

Fuchsia Rust 團隊維護了 Fuchsia Rust 程式庫的參考資訊。在 SDK 支援 Rust 之前，這些項目都託管於其他網站。

目前有一般的 Fuchsia 說明文件標準。