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

簡介

本文件內含為 Fuchsia 撰寫 API 說明文件的指南。它同時適用於公開 API (透過 SDK 顯示) 和 Fuuchsia 內部的 API。公開的 API 說明文件將由 API 委員會審查，確認是否遵循這項評分量表。

整體留言規則

在多數情況下，說明文件應遵循適用於註解的語言樣式指南。如果本文件中的規則與語言專用規則相牴觸，請遵循本文指南。在某些情況下，系統會優先採用語言專屬規則；以下將說明這些特殊情況。

以下為可能在 Fuchsia 存放區中使用的語言，提供特定語言指南的連結：C 和 C++、Rust、Java、Kotlin。建議您也參閱 Google 的 API 說明文件指南。

與照護人員溝通

Fuchsia 說明文件是公開的，使用時應以技術語氣和中立語氣撰寫。下方可撰寫的內容有一些明確的限制，但內容並不會全面性，請妥善判斷。

  • 請勿參考專屬資訊。包括個人識別資訊和驗證金鑰等個人識別資訊。
  • 請勿使用不雅言詞或其他可能令人反感的用語 (例如「蠢蛋」)

一般樣式

  • Fuchsia 使用美國英文，並且遵循 Fuchsia 文件標準和樣式指南
  • 請勿明確列出作者。隨著開發人員切換到不同專案，作者資訊很快就會過時。儘管如此，我們仍建議您提供維護人員檔案，不過這也要小心。
  • 根據預期顯示方式將程式碼最佳化 (例如：依照預期使用 Markdown 或 Javadoc)。

只有在沒有語言專屬做法和指導的情況下，才套用下列規則：

  • 說明文件應緊接在所記錄的元素之前。
  • 使用 Markdown 標記註解。Markdown 的樣式，是最有可能使用 API 的工具瞭解的樣式。
    • 程式碼區塊應使用反引號，而非 4 個空格縮排。
  • 所有評論都必須使用完整的句子。

API 元素

  • 公開 API 元素是指透過 SDK 提供給開發人員的 API。所有對外公開的 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 元素的淘汰狀態說明會降低 API 說明文件的品質，請考慮提供指標來提供更多資訊，包括網址和錯誤 ID。

API 行為

記錄使用者遇到的子類，以及前後條件。

  • 原則上，請確保有斷言 / 測試可強制執行這些條件。
  • 其中應記載需要使用者明確操作的先決條件和先決條件。例如，如果需要在任何其他發生前呼叫 Init() 方法，請提供說明文件。
  • 應記載參數或傳回值之間的關聯 (例如一個必須小於另一個值)。

並行

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

  • FIDL 伺服器可能會以無法預測的順序執行要求。說明文件應將可能會影響呼叫端觀察的行為納入考量。
  • 每個具備內部狀態的 API 都屬於下列其中一個類別。使用下列字詞記錄哪個編號：
    • 執行緒安全：這表示對於 API 的個別元素 (例如類別中的方法) 的叫用，與其他並行程序之間的不可部分完成。呼叫端不需要任何外部同步處理 (例如，呼叫端不應在方法叫用期間獲取鎖定)。如果呼叫端需要使用外部同步處理功能，讓其他執行緒能夠看見 API 的執行個體 (例如設定並取得不可部分完成運算的類別執行個體的全域指標)，您仍然可以將 API 描述為執行緒安全。
    • 執行緒無安全：這表示所有方法都必須使用外部同步處理來確保不變性 (例如鎖定強制執行的共同排除)。
    • 執行緒主機關係：這表示不應透過多個執行緒存取該 API 元素 (例如，其中的實作詳細資料依賴於背景中未同步的靜態資料存取權，例如 strtok())。這應包含執行緒相依性的說明文件 (例如使用執行緒本機儲存空間 (TLS))。只有在 Fuchsia API 中才能使用例外狀況。
    • 特殊：這表示需要考慮使用這個 API 的正確並行用途，請參閱說明文件。當需要初始化實體，並以特定方式發布實體的參照時，這一點尤其重要。
    • 不可變動：其他四個類別會假設內部狀態是可變動，且會保證執行緒安全性。不可變更的類別仍會持續顯示，而不會進行任何額外的同步處理，但您必須針對序列化 / 反序列化，以及在執行緒之間共用物件參照的方式維持嚴格的規則。
  • 如果 API 無法保證取得進度，就會封鎖 API。請記下 API 的封鎖屬性。
    • 如果 API 處於封鎖狀態，說明文件必須說明程式碼進行進度所需的必要條件，除非封鎖是需要瞭解實作的低機率事件。
      • 舉例來說，如果必須記錄方法的封鎖行為，便是在封鎖等待管道回應的情況。
      • 舉例來說，您不必記錄某個方法的封鎖行為，就是如果鎖定的星號鎖定是高負載下的理論可能性，就可能遭到封鎖。
    • 系統只會將 API 視為封鎖，因為需要很長的時間才能完成。不應記錄運作速度緩慢的演算法，以免造成封鎖。
    • 說明文件應只在 API 非阻斷行為對其使用至關重要時 (例如 API 傳回 Future)。
  • 如果 API 可能會在執行期間安全中斷，然後再次呼叫，則 API 為「必須」。記錄 API 的重複屬性。
    • API 可能會視為是剩餘。如果無法重新授權，說明文件必須說明。
  • 說明函式是否依賴執行緒本機儲存空間 (TLS) 維持不變，以及任何與該 TLS 相關的先決條件和先決條件 (例如，如果每個執行緒需要呼叫一個 Initializer)。

擁有權

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

  • 對於在函式生命週期過後儲存的參數或傳回值，或是函式分配並傳回至呼叫端的資源，或是具有特定擁有權限制的資源，必須由一組 API (即共用資源) 觀察，則必須記錄擁有權和有效性。
  • 請記下負責釋出任何相關資源的人員。
  • 在適當情況下，說明文件應說明釋出這些資源的通訊協定。如果 API 和 API 呼叫端的記憶體配置處理常式不同，就可能會遇到特殊問題。
    • 語言應在樣式指南中指出預設擁有權行為。

空值

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

  • 即使是在 Dart 中也一樣！
  • 在適用情況下，將參數和傳回值設為「null」 (可能包含空值) 或「非空值」 (不可包含空值)。

單位

所有參數和傳回類型的單位都必須明確定義 (無論是依據說明文件或類型)。

最佳做法

本節提供撰寫註解時應納入考量的指引。其中包含觀點，而非上述提供的明確規則。

  • 讀取器不應查看 API 實作方式來判斷其用途。建議您撰寫說明文件，讓讀者根據說明文件單獨實作 API。如果您需要提供 API 運作方式的其他詳細資訊，請在 Fuchsia.dev 上建立並連結至其他手冊。
  • 避免使用讀者對於讀者不知道的術語 (例如：「如果我對這個 API 感興趣，我絕對會知道這個字的意思？」)。如果術語是 Fuchsia 專屬且未定義，請將其新增至詞彙表。
  • 避免使用縮寫和縮寫。如果需要使用它們，請加以說明。如果業界經常使用這個縮寫 (例如「傳輸控制通訊協定 / 網際網路通訊協定」(TCP/IP)，但您不需要說明，但建議您提供連結以瞭解詳情。
  • 請將其視為有用的程式碼範例。提供範例通常能讓模式更清楚明瞭。建議您為每個頂層 API 元素 (例如類別) 使用 API 範例。
  • 您必須在註解中清楚說明 API 的使用方式。
    • 建議您將範例做為獨立程式撰寫並建立連結，但留意文件中的過時連結。
    • 範例應全部編譯和執行。
  • 當已閱讀文件的使用者提問，文件應該回答的問題時，請改善文件內容。
  • 一律加上值。請勿重寫類型簽章已標示的內容。「請勿重複自我」(DRY) 原則。下面為重複的資訊兩次，因此並不實用：
 /**
  * Returns an instance of Foo.
  * @return an instance of Foo.
  */
 public Foo getFoo() { ... }
  • 同樣地，如果註解顯然很明顯，請避免加入這項資訊。舉例來說，如果屬性是由類型系統保證，您不需要單獨記錄屬性。不過請記住，您的 API 說明應足以啟用獨立實作。
  • 請考慮記錄效能考量和資源消耗問題，但請注意，這類問題通常是因實作而異，而且會隨時間改變，您方法的合約可能保持不變。建議您改為在實作注意事項/版本資訊中加入這項資訊。
  • 避免建立非複合字詞的執行字詞。例如，「notready」代表兩個字同時執行。使用適當的分隔符，例如「notReady」、「notReady」、「not_ready」或「not-ready」)。
  • 除非特別指出該功能可能會隨時間而改變，否則請避免記錄可能隨時間大幅變動的功能。您提供的要求越多，未來維護人員的靈活性就越低。不過，瞭解這並不重要，因為使用者取決於所有行為。另請參閱海倫定律。