FIDL 樣式指南

這個部分包含以下項目的樣式相關資訊: Fuchsia Interface Definition Language 檔案。

另請參閱 FIDL API 評分量表

名稱

貓的命名並不容易,
不是只有一場節慶遊戲。
--- T.S.Eliot

在 FIDL 中定義的名稱,會用來產生每種譯文語言的 ID。 部分語言會在不同的名稱中附加語義或傳統意義 表單。例如,在 Go 中,ID 中的初始字母是否 大寫會控制 ID 的顯示設定。因此 語言後端會轉換您程式庫中的名稱,使其更加 打造適合目標語言的內容本節中的命名規則是 在 FIDL 來源的可讀性和各目標的可用性之間取得平衡 以及目標語言的一致性

請避免使用常用的字詞,例如 goto。語言後端 將保留字詞轉換為非保留 ID,但這些轉換 減少這些語言的可用性避免使用常見的保留字詞,可以減少 套用這些轉換的頻率

儘管某些 FIDL 關鍵字在目標語言中也是常見的保留字詞, (例如 C 和 C++ 中的 struct),因此應避免使用其他 FIDL 關鍵字 (尤其是 requesthandle) 通常是描述性字詞 您也可以視需要使用這些選項

名稱的開頭或結尾不得為底線。開頭或結尾 在某些語言中,底線 (例如開頭的底線) 具有語意含意 控制 DoubleClick 的可見性) 和其他語言 (例如 在 C++ 中,結尾的底線常用於成員變數。 此外,FIDL 編譯器會使用開頭和結尾的底線,以便統一處理 識別碼可避免衝突。

請使用 size 字詞為位元組數命名。請使用 count 這個字詞來命名 其他數量 (例如 結構體)。

案件定義

有時候,Google Analytics 中的 識別碼樣式如下:

  • 請使用英文 (美國) 的原始詞組 (例如「非空值 HTTP 用戶端」)
  • 請移除所有標點符號。(「非空值 HTTP 用戶端」)
  • 全部改為小寫 (「非空值 http 用戶端」)
  • 視指定的樣式,執行下列任一操作 ID:
    • 針對小寫蛇形大小寫,並以底線 (「_」) 取代空格 (non_null_http_client)。
    • 大寫字體,並以底線取代空格 (NON_NULL_HTTP_CLIENT)。
    • 每個字的首字母大寫,然後將所有單字合併在一起,以 大寫駝峰式大小寫 (NonNullHttpClient)。

用量

下表將案例使用情形對應至 元素:

元素 套管 範例
bits 大寫駝峰式大小寫 InfoFeatures
Bitfield 成員 大寫上層案件 WLAN_SNOOP
const 大寫上層案件 MAX_NAMES
alias 大寫駝峰式大小寫 DeviceId
protocol 大寫駝峰式大小寫 AudioRenderer
通訊協定方法參數 小寫保護殼 enable_powersave
通訊協定方法 大寫駝峰式大小寫 GetBatteryStatus
struct 大寫駝峰式大小寫 KeyboardEvent
結構體成員 小寫保護殼 child_pid
table 大寫駝峰式大小寫 ComponentDecl
資料表成員 小寫保護殼 num_rx
union 大寫駝峰式大小寫 BufferFormat
工會成員 小寫保護殼 vax_primary
enum 大寫駝峰式大小寫 PixelFormat
列舉成員 大寫上層案件 RGB_888

程式庫

程式庫名稱是以半形句號分隔的 ID 清單。圖書館的部分內容 也稱為命名空間每個元件的 名稱必須為小寫,且必須符合下列規則運算式: [a-z][a-z0-9]*

由於不同的目標語言各有不同,因此我們使用上述限制性規則 限制命名空間、程式庫或套件評估方式。我們 選用保守的最小公分母,FIDL 才能順利運作 搭配現行的指定語言組合,以及潛在的未來目標 語言。

ID 名稱:偏好具有意義的功能角色

優先使用函式名稱 (例如fuchsia.media) 高於產品或代碼名稱 (例如:fuchsia.amberfuchsia.scenic)。建議使用合適的產品名稱 當產品對於 Fuchsia 以外的外部存在, 專屬通訊協定例如,fuchsia.cobalt 是 Cobalt 介面通訊協定的名稱優於 fuchsia.metrics 其他指標的導入方法 (例如Firebase) 不太可能導入 因此效能相當卓越

ID 名稱應與參與者扮演的特定角色有關。 避免對名稱進行編碼存取控制依據角色分類的名稱 名稱不會因存取權控管而異,且不會如預期般迅速更新, 指涉外部定義的關係,此關係可能會隨著 不斷進化舉例來說,如果 API 涉及 FocusChain 物件, 適當名稱應為 fuchsia.ui.focus,而不是 fuchsia.ui.privileged;如果我們決定將 FocusChain 物件擴大 表示 fuchsia.ui.focus 不是問題名稱,下列 範例字詞 應避免使用:

  • constrained
  • limited
  • oem
  • private
  • privileged
  • protected
  • special
  • vendor

ID 名稱應具有意義;避免使用無意義的名稱如果 fuchsia.foo.barfuchsia.foo.baz 都分享了一些概念 建議在獨立的程式庫中 fuchsia.foo而非 fuchsia.foo.common。下列範例字詞 請避免:

  • common
  • service
  • util
  • base
  • f<letter>l
  • zx<word>

頂層

避免重複使用程式庫名稱中的名稱。例如,在 fuchsia.process 程式庫,啟動程序的通訊協定應命名 Launcher 而非 ProcessLauncher,因為「process」這個名稱已經存在 。在所有目標語言中,頂層名稱都是 界定範圍是程式庫名稱的範圍

原始別名

原始別名不得與封閉資料庫中的名稱重複。所有 目標語言,原始別名會替換為基礎原始別名 因此不會造成名稱衝突。

alias vaddr = uint64;

常數

常數名稱不得與外圍程式庫中的名稱重複。在所有目標區間內 常數名稱的範圍取決於其內附程式庫。

用來說明下限和上限的常數應使用前置字串 MIN_MAX_

const MAX_NAMES uint64 = 32;

通訊協定

通訊協定是透過 protocol 關鍵字指定。

通訊協定必須為名詞片語。 通訊協定通常是以建議動作的名詞命名。適用對象 例如,AudioRenderer 是名詞,表示通訊協定相關 才能轉譯音訊同樣地,Launcher 是名詞,表示 與啟動項目有關通訊協定也可以 尤其是與實作所持有州名相關的名詞。 例如,Directory 是名詞,表示通訊協定會用於 與實作中的目錄互動。

通訊協定能以物件導向設計模式命名。例如: fuchsia.fonts.Provider 使用 provider 後置字串,表示 通訊協定提供的是字型,而不是代表字型本身。同樣地 fuchsia.tracing.Controller 使用 controller 後置字串,表示 通訊協定會控制追蹤系統 (而不是代表追蹤 其本身)。

Manager」這個名稱可做為含有 例如:fuchsia.power.Manager。不過請注意 「管理員」通常會吸引大量鬆散的通訊協定 這類功能可能更適合納入多個通訊協定。

通訊協定不得含有名稱 service.。所有通訊協定都會定義服務。 這個字詞沒有任何意義。舉例來說,fuchsia.tts.TtsService 違反了 評分量表首先,Tts 前置字串與程式庫重複 名稱。第二,Service 字尾是禁止的。

明確「open/ajar/closed」修飾符

請務必指定通訊協定,應一律指定 openajarclosed 不必仰賴預設值也就是說,一律將 open protocol Foo { ... 設為只使用 protocol Foo { ...

方法

方法必須為動詞片語。

舉例來說,GetBatteryStatusCreateSession 是 指出該方法執行的動作。

事件時呼叫的 listenerobserver 通訊協定的方法 應該以 On 做為前置字元,並說明 時態例如,ViewContainerListener 通訊協定有一個方法 OnChildAttached

活動

同樣的,事件 (例如從伺服器傳送至用戶端的來路不明郵件) 應加上 On 的前置字串,並說明過去發生的事件 緊張刺激。

舉例來說,AudioCapturer 通訊協定包含一個名為 OnPacketCaptured

單一方法通訊協定

其中一種方法通訊協定的方法應為 所定義通訊協定的名詞片語,例如Loader.LoadGetter.GetUploader.Upload。如果是限定名詞片語,例如 JobCreatorProcessStopper,請使用不合格的動詞詞組,例如 JobCreator.CreateProcessStopper.Stop

單純是單一方法的通訊協定,但預計會隨著時間演進多方法 不一定需要遵循這個命名慣例 非建議命名的通訊協定擴充欄位 建議盡早選擇其他名稱位於 也不需要遵循預設的建議。

因為取代通訊協定比改進通訊協定困難 因而需要改用多種方法 因此建議您新增方法,將現有的通訊協定演進。 且可能重新命名現有方法

煽情露骨內容「strict/flexible」修飾符

對於方法和事件,請一律指定 strictflexible 不必仰賴預設值也就是說,一律將 flexible Foo(); 設為 只要 Foo()

結構、聯集和表格

結構體、聯集和資料表必須為名詞片語。 舉例來說,Point 是定義了空間中的位置的結構, KeyboardEvent 是定義鍵盤相關事件的結構體。

結構、聯集和資料表成員

使用單一字詞時,優先使用 struct、聯集和資料表成員名稱 實在 (單字名稱在所有目標語言的搜尋結果中較為一致)。 但是,如果單一字詞的 內容模糊或混淆。

成員名稱不得重複從所屬類型 (或資料庫) 中重複使用,除非 但不包含所屬類型中的名稱,所以會員名稱不明確。適用對象 例如,KeyboardEvent 類型的成員只要包含事件發生的時間 傳遞的檔案名稱應為 time,而不是 event_time,因為名稱 event 已出現在所屬類型名稱中。在所有目標區間內 成員名稱取決於其包含類型

然而,DeviceToRoom 類型會將智慧型裝置與會議室建立關聯 這個工作區位於 ,可能需包含 device_idroom_name 成員,因為 「id」和「name」不正確。其中一項可能就是 或是房間或某個房間

列舉

列舉必須是名詞片語。

舉例來說,PixelFormat 這個列舉會定義顏色編碼方式 轉換為圖像中的位元

列舉成員

列舉成員名稱不得與外圍類型 (或資料庫) 中的名稱重複。 舉例來說,PixelFormat 列舉的成員應命名為 ARGB,而非 PIXEL_FORMAT_ARGB,因為名稱中已有「PIXEL_FORMAT」這個名稱 就屬於封閉類型在所有目標語言中,列舉成員名稱的範圍都是 其包圍類型

比特田

位元欄位必須為名詞片語。

舉例來說,InfoFeatures 是位元欄位,用於指出哪些地圖項目 都會出現在乙太網路介面上

Bitfield 成員

Bitfield 成員的類型 (或程式庫) 中不得使用重複名稱。 舉例來說,InfoFeatures 位元欄位的成員應命名為 WLAN 而非 INFO_FEATURES_WLAN,因為「INFO_FEATURES」名稱已存在 會顯示在封閉類型的名稱中 在所有目標語言中,位元欄位成員名稱的範圍都是 封閉類型。

類型

煽情露骨內容「strict/flexible」修飾符

適用於接受 strict/flexible 修飾符的類型 (bitsenumunion),因此應一律指定這類修飾符,而非依賴 預設值。也就是說,一律將 flexible bits ... 設為只使用 bits ...

機構

語法

  • 使用 4 個空格縮排。
  • 不使用分頁。
  • 避免在結尾加上空白字元。
  • bitsenumprotocolstructtable 和 和 union 則來自其他宣告 一行空白行 (兩個連續的換行字元)。
  • 僅有一個換行字元的檔案結尾。

留言

註解使用 /// (三個正斜線)。媒體庫中的註解也會 才會出現在系統產生的程式碼中,方便您在根據 資源庫。表示留言會「流暢」翻譯成目標語言

將意見放在描述內容上方。除了所列案例以外 請使用適當的大小寫和正確的句子, 。除非留言較長,否則留言寬度限制在 80 個字元以內 難以避免的情況 (例如,過長的網址)。

註解應使用 Markdown 撰寫。我們仰賴 Markdown 的 CommonMark 規格。只有部分通知 工具可能會使用其他 Markdown 標準轉譯輸出內容。為了讓你的工具 並未使用 CommonMark,我們鼓勵開發人員撰寫 Markdown 可與 CommonMark 及其工具相容參照 FIDL 元素 一律使用程式碼字型。

記錄實體是指任何有附加註解的 FIDL 元素。第一個 應提供註解中任何文件實體的參考資料 合格名稱,格式為 [`<library>/<top level declaration>.<member>`] (例如:[`fuchsia.io/Node.clone`])。如果 部分工具後續參照該文件實體時, 使用縮寫,但前提是內容不明確 (例如:clone)。不含括號的表單不會產生超連結。

請求參數、回應參數和錯誤類型應記錄為 表單清單:

+ request `param1` <description>
+ request `param2` <description>
- response `param1` <description>
- response `param2` <description>
* error <description>

要求、回應和錯誤必須依序顯示。一組指定的 參數也必須遵循 參數清單「要求」一詞和「response」而不需加以顯示 參數名稱只會出現在其中一個要求或回應參數清單中。

文件註解中,用來描述變數、欄位或類型的第一部分應為 用來簡短陳述文件所列實體預期用途的名詞片語。 包括無法從名稱和類型中估算出的資訊。 說明必須以句點結尾說明不得 重複記錄實體的名稱,或該實體的特定類型 FIDL 語言元素 (例如structprotocol)。

/// A representation of violins displayed on the screen.
type Widget = struct {
    /// A monotonically increasing id, uniquely identifying the widget.
    id uint64;
    /// Location of the top left corner of the widget.
    location Point;
};

以下列舉幾個不得採取的行動:

/// BAD: Widget is a representation of violins displayed on the screen.
/// BAD: struct Widget is a representation of violins displayed on the screen.

文件註解附加至通訊協定方法的第一部分應為簡短 該方法行為的說明,從動詞開頭,包括 從名稱和類型中無法估算出的資訊。動詞應該是 看正確的人稱代名詞 使用直陳語氣 (這實際上意味著您應該假裝 「it」而您要做的是事實聲明)。 詞組的結尾應為句號

完整範例:

/// An abstract representation of a [`fuchsia.io/Node`] whose layout is flat.
protocol File {
    compose Node;

    /// Acquires a [`fuchsia.mem/Buffer`] representing this file, if
    /// there is one, with the requested access rights.
    ///
    /// ## Rights
    ///
    /// This method requires the following rights:
    ///
    /// * [`fuchsia.io/OPEN_RIGHT_WRITABLE`] if `flags` includes
    ///   [`fuchsia.io/VMO_FLAG_WRITE`].
    /// * [`fuchsia.io/OPEN_RIGHT_READABLE`] if `flags` includes
    ///   [`fuchsia.io/VMO_FLAG_READ`] or [`fuchsia.io/VMO_FLAG_EXEC`].
    ///
    /// + request `flags` a bit field composing any of
    ///     `VMO_FLAG_READ`, `VMO_FLAG_WRITE`, or `VMO_FLAG_EXEC`.
    /// - response `buffer` the requested `fuchsia.mem/Buffer`, or
    ///     null if there was an error, or the buffer does not exist.
    /// * error a zx_status value indicating success or failure.
    /// * see [`fuchsia.mem/Buffer`]
    /// [`fuchsia.mem/Buffer`]:
    ///    https://fuchsia.googlesource.com/fuchsia/+/HEAD/sdk/fidl/fuchsia.io/
    GetBuffer(struct {
        flags uint32;
    }) -> (resource struct {
        buffer box<fuchsia.mem.Buffer>;
    }) error zx.Status;
};

某些外部可靠來源定義的類型或值應加上註解 參照外部事物例如使用 Wi-Fi 描述設定結構同樣地, 結構必須與 C 標頭中定義的 ABI 相符,請參照 C 標頭。

如要進一步瞭解註解應包含的內容,請參閱 API 說明文件評分量表

參照 FIDL 通訊協定或通訊協定方法

提及 FIDL 通訊協定或其方法時,必須遵守 模式:

/// See fuchsia.library/ProtocolName.Method for more information.

參照與註解所在程式庫中的通訊協定時,程式庫 名稱可能維持不變:ProtocolName.Method

同樣地,在與註解相同的通訊協定中參照方法時, 請保留程式庫名稱和通訊協定名稱:Method

程式庫總覽

您可以透過說明文件註解, library 陳述式。程式庫陳述式啟動 FIDL 檔案。例如:

/// Library containing example FIDL used throughout the Fuchsia documentation.
library fuchsia.examples.docs;

程式庫總覽應提供定義程式庫的一般說明文件。 他們也可能會針對各種訊息提供詳細的簡介 通訊協定,以及這些訊息與通訊協定如何搭配使用。

雖然一個程式庫可細分為多個 FIDL 檔案,但 只能設為單一程式庫總覽。請參考這些媒體庫的建議 總覽:

  • 如果總覽很短,且資料庫內含單一檔案,您可以 請將總覽放在程式庫檔案頂端的 library 陳述式中。
  • 如果程式庫包含多個檔案,請建立獨立檔案 overview.fidl 以記錄程式庫。「overview.fidl」檔案不得 包含任何宣告、類型別名或通訊協定定義。

非流量式留言

如果您是要給圖書館作者的留言,請提供更簡潔的註解 // (兩條正斜線),不會流向目標語言。

決定要建立一般 /// 註解和非資料流動時 留言,請記住下列事項

定期留言:

  • 參數、引數、函式的說明
  • 使用須知

非流量式留言:

  • 內部「待辦事項」留言
  • 著作權聲明
  • 導入作業詳細資料

這兩種類型的註解皆可合併:

/// A widget displaying violins on the screen.
// TODO -- widgets should use UUIDs instead of sequential ids
type ViolinWidget = struct {
    /// A monotonically increasing id, uniquely identifying the widget.
    id uint64;
    /// Location of the top left corner of the widget.
    location Point;
};

檔案

程式庫由一或多個檔案組成,檔案儲存在 並遵循以下慣例:

fidl/<library>/[<dir>/]*<file>.fidl

<library> 目錄是以 FIDL 的點分隔名稱命名 資源庫。<dir> 子目錄是選擇性的,通常不適用於 內含不到十幾個檔案的程式庫這個目錄結構符合 Fuchsia SDK 中包含 FIDL 檔案。

將程式庫分割為多個檔案,對 資源庫。宣告 (包括通訊協定) 可以彼此參照 整個程式庫中看起來都一樣。 將程式庫分成多個檔案,盡可能提升可讀性。

  • 建議程式庫中的檔案使用 DAG 依附元件圖表。
  • 建議讓雙向參照定義文字彼此靠近 最好放在同一個檔案中
  • 如為複雜的程式庫,建議在分葉中定義純資料類型或常數 檔案,以及定義在主幹中參照這些型別的通訊協定 檔案。