API 說明文件可讀性評分量表

總覽

本文件提供 Fuchsia 的 API 說明文件編寫指南。這項服務 同時適用於公開 API (透過 SDK 顯示) 是 Fuchsia 內部的 Pod。公開的 API 說明文件將由 API 委員會 。

整體註解規則

在大部分情況下，說明文件應該遵循 留言。如果本文件中的規則與 建立特定語言專屬的規則時，請按照本文件的指示進行。在某些情況下， 語言專屬規則的優先順序較高；這些特殊情況歸功於 。

以下各連結說明瞭適用的語言， 用於 Fuchsia 存放區中的區別： C 和 C++ Rust、 Java、 Kotlin。 我們也建議您參閱 Google 的 API 指南 說明文件。

與照護溝通

Fuchsia 說明文件為公開資訊，且應 而且用上去的技術性和性調性此外，我們也有明確的限制 下方可撰寫的內容，但這些不是完整內容，請使用 太棒了！

  • 請勿提及專屬資訊。包括個人 個人識別資訊 (例如個人識別資訊) 驗證金鑰
  • 請勿使用髒話或其他可能令人反感的用語 (例如 例如：「笨蛋」)

一般樣式

  • Fuchsia 使用英文 (美國) 做為語言，然後跟隨 Fuchsia 文件標準和 格式指南
  • 請勿明確列出作者。作者資訊很快就過時， 隨著開發人員遷移至不同的專案考慮提供維護人員 檔案，但請注意，此次過期。
  • 將程式碼最佳化，以便顯示預期的顯示畫面 (例如，使用 Markdown 或 Javadoc， )。

請只在沒有語言專屬做法的情況下套用下列規則，以及 指南：

  • 說明文件應緊接在文件記錄的元素前面。
  • 使用 Markdown 撰寫註解。Markdown 的樣式是 產生最可能使用 API 的工具
    • 請在程式碼區塊中使用倒引號，而不要使用 4 個空格縮排。
  • 所有註解都應該使用完整的句子。

API 元素

  • 一個公開的 API 元素是提供給開發人員使用的一個 透過 SDK所有公開的 API 元素 (包括但不限於 方法、類別、欄位、類型) 都必須包含說明。內部程式庫 文件而應該有理由拒絕

  • 所有參數都必須提供說明，除非該說明 以類型和名稱重複。

    • 如果無法從類型中明顯看出參數的法律值， 請考慮變更類型舉例來說，{-1, 0, 1} 不實用 列舉含 {LESS_THAN、EQUAL_TO、GREATER_THAN}。
    • 否則，請記錄所有可能輸入值的 API 行為。 我們不建議使用未記錄的值。

  • 所有傳回值都必須包含說明，除非該說明為 以類型和名稱重複。

    • 如果方法或函式傳回其傳回類型的子集， 子集。
    • 記錄所有傳回的錯誤，以及這些錯誤會發生的情況 產生的結果。
    • 例如，如果方法的傳回類型是 zx_status_t，且 會傳回 ZX_OK 和 ZX_ERR_INVALID_ARGS，您的說明文件必須 明確列出
    • 如果無法立即得知特定回傳值代表的意義 必須妥善記錄例如，如果方法傳回 ZX_OK，您就不會 不需要記錄下來。如果方法傳回字串長度，則 文件。

  • 所有擲回的例外狀況都必須提供說明，且必須包括 限制的擲回條件，除非類型與 名稱。

    • 有些第三方程式碼無法一致記錄例外狀況。這可能會 難以 (或無法) 記錄這類程式碼的行為 相互整合可以盡量採取最適當的做法；可以解決這類問題 發生的機率。
    • 記錄例外狀況是否可復原，如果可以，並說明如何復原 。

  • 針對任何可延伸的 API 元素，指出其是否為預期 以及想擴展業務員的需求條件

    • 如果 API 基於內部原因 (例如測試) 可擴充，請參閱說明文件 這些資料。舉例來說，如果您允許某個類別 擴充，方便建立測試替身。

  • 文件已淘汰的 API 元素。

    • 已淘汰 API 元素的說明文件必須說明使用者預期的內容 不必使用 API
    • 並明確記錄將停用 API 的計畫 (如果有的話)。
    • 若說明 API 元素的淘汰狀態會減少 API 說明文件的品質，請考慮提供指標， 包括網址和錯誤 ID 等

API 行為

記錄使用者實際看到的不變數，以及事前/事後成因。

  • 原則上，如要強制執行這些宣告 / 測試 條件。
  • 要求使用者明確操作的先決條件和附加條件 。舉例來說，如果 Init() 方法有誤，請提供說明文件 必須先呼叫才會發生作用
  • 參數或傳回值之間的關係 (例如：必須減少一個參數) 與其他文件

並行

記錄有內部狀態的 API 並行屬性。

  • FIDL 伺服器可能會以無法預測的順序執行要求。說明文件 考慮此舉可能會影響呼叫端行為的情況。 觀察結果。
  • 每個具有內部狀態的 API 都屬於下列其中一個類別。 使用下列條款記錄具體問題：
    • 安全執行緒：這是指叫用 API 的個別元素 (例如類別中的方法) 與其他並行作業相比，屬於不可分割的形式 作業。呼叫端不需要使用任何外部外部 IP 位址 (例如，呼叫端不應取得 擷取的持續時間)。您仍可以 如果呼叫端需要使用外部同步處理功能來 其他執行緒都能看到的 API 執行個體參照 (例如 設定並取得全域指標，指向具有原子物件的類別例項 作業)。
    • 無執行緒安全：這表示所有方法都必須使用外部 同步處理，確保維持不變動 (例如 排除)。
    • 執行緒主機：這表示不應存取該 API 元素 從多個執行緒擷取而來 (例如，其中有依賴於 非同步對靜態資料 (例如 strtok()) 的存取權)。 這應包含執行緒相依性的說明文件，例如使用 執行緒本機儲存空間 (TLS))。只有 Fuchsia API 例外。
    • 特殊：這是指正確同時使用這個 API 的情況 需要有謹慎思考，請詳閱說明文件這特別適合用在 您需要初始化實體，並參照發布在 建立個別符記
    • 不可變動：其他四個類別會假設內部狀態是 可變動和執行緒安全則是由同步處理確保。不可變動 類別會持續顯示，沒有任何其他同步處理 必須維持嚴格的序列化 / 還原序列化規則 物件參照如何在執行緒之間共用。
  • 如果 API 不保證會進度，就會遭到封鎖。文件 封鎖 API 的封鎖屬性
    • 如果 API 處於封鎖狀態，說明文件必須說明 使程式碼有所進展，除非封鎖是導致 這包括實作方式
      • 舉例來說，如果您必須記錄方法的封鎖行為， 阻止等待管道回應
      • 無須記錄方法的封鎖情形 如果理論上鎖飢感，就能阻止攻擊
    • API 需要很長的時間才能完成，因此不算是封鎖 完成。緩慢演算法不應記錄為封鎖。
    • 說明文件應只指出當 非封鎖行為對使用行為至關重要 (例如 API 描述 會傳回 Future)。
  • 如果 API 在運作期間安全中斷，就會保留 然後再次呼叫記錄你的 相互整合
    • 系統可能會假設 API 才重新申請。說明文件必須說明 無法重新申請。
  • 記錄函式是否依賴執行緒本機儲存空間 (TLS) 維持其不變體，以及與 該 TLS (例如需要使用每個執行緒呼叫初始化器一次時)。

擁有權

文件擁有權和有效性屬性。

  • 針對在 或由函式分配，並回傳至 或具有特定擁有權限制的資源 透過一組 API (即共用資源)、擁有權和有效性 必須妥善記錄
  • 記錄負責發布任何相關資源的人員。
  • 在適當的情況下，說明文件應指出要發布的通訊協定 管理這些資源如果記憶體配置與記憶體用量分配問題 常式也各有不同
    • 語言應以風格強調預設擁有權行為 指南。

空值

所有參數和傳回值都必須定義空值屬性 (如果 屬於可為空值類型)。

  • 即使是在 Dart 中！
  • 在適當情況下，參照參數並將值傳回為 nullable (或 包含空值) 或非空值 (不可包含空值)。

單位

不論是哪一種參數和傳回類型，單位都必須明確定義單位 (無論 說明文件或類型)。

最佳做法

本節說明在下列情況下應納入考量的指引： 來撰寫留言這牽涉到意見，而非明確制定的規則 。

  • 讀者不必查看 API 的實作內容，就能瞭解 雲端運算的工作請考慮撰寫說明文件，讓讀者 並根據說明文件獨立實作 API如需提供 進一步瞭解 API 運作方式，建立並連結其他員工 前往 Fuchsia.dev 頁面
  • 避免使用難以理解的術語 (思考 ，我完全可以知道這個字的意思？」。如果 術語是與 Fuchsia 專用且未定義，請將其新增至詞彙表。
  • 避免使用縮寫和首字母縮寫。需要時請詳加說明。 如果縮寫是業界廣泛使用 (例如"傳輸 控制通訊協定 / 網際網路通訊協定」(TCP/IP))，因此您不必 但建議您提供其他背景資訊的連結
  • 無論樣本有沒有幫助，都應將程式碼範例納入考量。提供 參考範例往往能讓模式更清楚易懂建議您使用 API 範例 每個頂層 API 元素 (例如類別) 的所有屬性。
  • 並在註解中清楚說明 API 的使用方式。
    • 建議分別撰寫範例做為個別程式，並連結至這些程式，不過 依據文件過時的連結
    • 範例都應全部編譯並執行。
  • 當閱讀文件的使用者提出一個應由 提昇文件品質
  • 請一律提供附加價值。請勿修正類型簽章已指定的內容。 「請勿重複自我」(DRY) 原則適用於。以下是 不實用，因為可能會重複相同的資訊：
 /**
  * Returns an instance of Foo.
  * @return an instance of Foo.
  */
 public Foo getFoo() { ... }
  • 同樣地，如果留言很顯而易見，請避免製作明顯的留言。舉例來說 類型系統保證屬性，因此您不必 。不過請注意，您的 API 說明必須足夠 以便獨立實作
  • 考慮記錄效能考量因素和資源用量 提醒你，這類問題通常取決於導入作業 並隨著時間變動 保持不變建議在導入附註中加入這項資訊 / 版本資訊。
  • 避免建立非複合字詞的跑步字詞。例如「notready」 代表兩個字詞共同運作使用合適的分隔符，例如「尚未就緒」 「notReady」、「not_ready」或「not-ready」)。
  • 請避免記錄可能隨時間變化迅速變化的功能。 除非您特別提到，否則這項功能可能會隨時間改變。愈多 您為日後維護人員提供的彈性變少了。不過 並不重要，因為使用者需仰賴 行為另請參閱「Hyrum's Law」。