這個部分包含以下項目的樣式相關資訊: Fuchsia Interface Definition Language 檔案。
另請參閱 FIDL API 評分量表。
名稱
貓的命名並不容易,
不是只有一場節慶遊戲。
--- T.S.Eliot
在 FIDL 中定義的名稱,會用來產生每種譯文語言的 ID。 部分語言會在不同的名稱中附加語義或傳統意義 表單。例如,在 Go 中,ID 中的初始字母是否 大寫會控制 ID 的顯示設定。因此 語言後端會轉換您程式庫中的名稱,使其更加 打造適合目標語言的內容本節中的命名規則是 在 FIDL 來源的可讀性和各目標的可用性之間取得平衡 以及目標語言的一致性
請避免使用常用的字詞,例如 goto
。語言後端
將保留字詞轉換為非保留 ID,但這些轉換
減少這些語言的可用性避免使用常見的保留字詞,可以減少
套用這些轉換的頻率
儘管某些 FIDL 關鍵字在目標語言中也是常見的保留字詞,
(例如 C 和 C++ 中的 struct
),因此應避免使用其他 FIDL
關鍵字 (尤其是 request
和 handle
) 通常是描述性字詞
您也可以視需要使用這些選項
名稱的開頭或結尾不得為底線。開頭或結尾 在某些語言中,底線 (例如開頭的底線) 具有語意含意 控制 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.amber
或 fuchsia.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.bar
和 fuchsia.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
」修飾符
請務必指定通訊協定,應一律指定 open
、ajar
或 closed
不必仰賴預設值也就是說,一律將 open protocol Foo {
...
設為只使用 protocol Foo { ...
。
方法
方法必須為動詞片語。
舉例來說,GetBatteryStatus
和 CreateSession
是
指出該方法執行的動作。
事件時呼叫的 listener
或 observer
通訊協定的方法
應該以 On
做為前置字元,並說明
時態例如,ViewContainerListener
通訊協定有一個方法
OnChildAttached
。
活動
同樣的,事件 (例如從伺服器傳送至用戶端的來路不明郵件)
應加上 On
的前置字串,並說明過去發生的事件
緊張刺激。
舉例來說,AudioCapturer
通訊協定包含一個名為
OnPacketCaptured
。
單一方法通訊協定
其中一種方法通訊協定的方法應為
所定義通訊協定的名詞片語,例如Loader.Load
、Getter.Get
、
Uploader.Upload
。如果是限定名詞片語,例如 JobCreator
或 ProcessStopper
,請使用不合格的動詞詞組,例如
JobCreator.Create
或ProcessStopper.Stop
。
單純是單一方法的通訊協定,但預計會隨著時間演進多方法 不一定需要遵循這個命名慣例 非建議命名的通訊協定擴充欄位 建議盡早選擇其他名稱位於 也不需要遵循預設的建議。
因為取代通訊協定比改進通訊協定困難 因而需要改用多種方法 因此建議您新增方法,將現有的通訊協定演進。 且可能重新命名現有方法
煽情露骨內容「strict
/flexible
」修飾符
對於方法和事件,請一律指定 strict
或 flexible
不必仰賴預設值也就是說,一律將 flexible Foo();
設為
只要 Foo()
。
結構、聯集和表格
結構體、聯集和資料表必須為名詞片語。
舉例來說,Point
是定義了空間中的位置的結構,
KeyboardEvent
是定義鍵盤相關事件的結構體。
結構、聯集和資料表成員
使用單一字詞時,優先使用 struct、聯集和資料表成員名稱 實在 (單字名稱在所有目標語言的搜尋結果中較為一致)。 但是,如果單一字詞的 內容模糊或混淆。
成員名稱不得重複從所屬類型 (或資料庫) 中重複使用,除非
但不包含所屬類型中的名稱,所以會員名稱不明確。適用對象
例如,KeyboardEvent
類型的成員只要包含事件發生的時間
傳遞的檔案名稱應為 time
,而不是 event_time
,因為名稱
event
已出現在所屬類型名稱中。在所有目標區間內
成員名稱取決於其包含類型
然而,DeviceToRoom
類型會將智慧型裝置與會議室建立關聯
這個工作區位於 ,可能需包含 device_id
和 room_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
修飾符的類型 (bits
、enum
和
union
),因此應一律指定這類修飾符,而非依賴
預設值。也就是說,一律將 flexible bits ...
設為只使用 bits ...
。
機構
語法
- 使用 4 個空格縮排。
- 不使用分頁。
- 避免在結尾加上空白字元。
bits
、enum
、protocol
、struct
、table
和 和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
語言元素 (例如struct
或 protocol
)。
/// 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 依附元件圖表。
- 建議讓雙向參照定義文字彼此靠近 最好放在同一個檔案中
- 如為複雜的程式庫,建議在分葉中定義純資料類型或常數 檔案,以及定義在主幹中參照這些型別的通訊協定 檔案。