在 Fuchsia 顯示驅動程式中參照資訊來源

本文建議的格式包括：

  • 參照：每個專案的清單，將簡短標記繫結至外部資訊來源
  • 引文：將程式碼繫結至參照文件內精確位置的一行註解
  • 別名：單行記錄，將程式碼使用的名稱繫結至其參照使用的名稱

這些格式經過最佳化，可供 AI 代理程式和指令碼直接或透過工具處理。可讀性至關重要，因此我們明確降低了人工撰寫的便利性。

引用、參照和別名的格式

摘要：

  • 每行一筆記錄，後面加上獨特的符號。
    • 引文使用 @cite，參考資料使用 @ref，別名使用 @alias。
    • 所有記錄都使用同一種文法。
  • 標記會以半形括號括住。
  • 所有其餘資料都是不區分順序的 key=value 欄位，並以 分隔。

文法

記錄：

record      = sigil "(" tag ")" ":" 1*( SP field )   ; exactly one SP before each field
sigil       = %s"@cite" / %s"@ref" / %s"@alias"
tag         = lower-alnum *( lower-alnum / "_" / "-" )
field       = key "=" value
key         = lower-alpha *( lower-alnum / "-" )     ; "x-" prefix reserved for experimental keys
value       = bare / quoted
bare        = 1*bare-char
quoted      = DQUOTE *( escaped / quoted-char ) DQUOTE
escaped     = backslash ( DQUOTE / backslash )       ; \" and \\ are the only escapes
bare-char   = %x21 / %x23-7E / %x80-10FFFF           ; excludes SP, HTAB, DQUOTE, all controls
quoted-char = %x20-21 / %x23-5B / %x5D-7E / %x80-10FFFF
                                                     ; excludes DQUOTE, backslash, all controls
backslash   = %x5C
lower-alpha = %x61-7A                                ; a-z
lower-alnum = lower-alpha / DIGIT

原始碼嵌入記錄：

source-line = *WSP "//" *WSP record          ; normative in-source form (citations, aliases,
                                             ; and @ref blocks in foreign files)
readme-line = "* " backtick record backtick  ; README bullet form
backtick    = %x60

文法詳細資料：

  • ABNF (RFC 5234)，並以 RFC 7405 (區分大小寫的字串常值) 擴充
  • 終端值是萬國碼純量值。
  • 來源檔案為 UTF-8。
  • RFC 5234 附錄 B.1 的核心規則：
    • SP (空格，%x20)
    • HTAB (水平定位字元，%x09)
    • DQUOTE (", %x22)
    • 數字 (0-9，%x30-39)
    • WSP (SP / HTAB)

參考資料

範例

擁有的專案 README 區段：

## References

* `@ref(virtio): kind=doc title="Virtio 1.4" version=1.4 date=2024-06-27 url=https://docs.oasis-open.org/virtio/... local=local/virtio/virtio-1.4.md`
* `@ref(socdb): kind=db title="SoC register database" version=1.4 local=docs/refs/soc-regs.json`

非您擁有的專案檔案：

// clang-format off
// @ref(freebsd): kind=code title="FreeBSD kernel" version=12.0.0 pin=release/12.0.0 url=https://cgit.freebsd.org/src/ local=local/freebsd
// clang-format on

鍵

kind 會選取引文鍵字彙。此為必要項目。有效值：

  • doc - 文件
  • code - 參考代碼
  • db - 資料庫
  • 實驗性關鍵字詞集的前置字元 x-

title 必須與資訊來源的聲明標題一致 (如有)。 必填。

version、revision、date 必須與資訊來源的中繼資料相符 (如有)。

url 是資訊來源的標準網頁網址。強烈建議使用。

pin 是提交雜湊或發布標記。kind=code 必須提供這項資訊。

local 是資訊來源本機快取的建議路徑。 相對於 Fuchsia 存放區根目錄。AI 代理會先查看這裡。

位置

擁有的專案：

  • README 區段「參考資料」是項目符號清單。
  • 每個項目符號都是以反引號括住的 @ref 記錄。

非您擁有的專案檔案：

  • 檔案頂端的註解區塊。
  • 每一行都是一個 @ref 記錄，範圍限定於該檔案。

版本管理

預設為簡短的無版本標記。@ref 記錄包含版本資訊。

遷移至新版資訊來源：在一個位置編輯 version=/revision=/date=/pin=，然後稽核每個 @cite。

如果新版未涵蓋舊版，且專案可能需要參照多個版本，請使用含版本的標記 (usb32 旁邊的 usb4)。

引用

範例

// @cite(virtio): sec=2.7 title="Virtqueues" page=30-31
// @cite(e-edid): sec=2.2 title="EDID Extension Blocks" page=16 q="if the maximum value of N is ‘1’"
// @cite(freebsd): file=sys/dev/drm2/i915/intel_ddi.c lines=718-735 sym=intel_ddi_mode_set
// @cite(socdb): key=/root/mipi_dsi0/PHY_STATUS bits=4:1

在任何註解行首之後，這些位元組都適用：

// @cite(e-edid): sec=2.2 title="EDID Extension Blocks" page=16

// @cite(virtio): sec=5.7.3 title="Feature bits" page=197-198 note="EDID needs feature negotiation"

依參照分類的重要詞彙 kind

doc (文件)

必須包含 sec (區段) 或 page。

page 是列印的頁碼；備用值：PDF 序號。在轉換後的 Markdown 中，page 是最接近前一個 <!-- page N --> 標記的 N。(PDF 和轉換後的 Markdown 語意相同)。

title 是章節標題。如果 sec 存在，則為必要欄位。

q (引號) 是簡短的原文詞組 (最多 10 個字)，用來錨定確切段落。

code

必須包含 file，這是參考項目所釘選樹狀結構內解析的路徑。

必須包含 sym (符號 / ID 名稱) 或 lines (<line> 或 <start>-<stop>)。最好兩者都包含。

DeviceTree 繫結是核心樹狀結構的kind=code引用。

db (資料庫)

key 是識別資料庫項目的主鍵。必填。

通用

bits=<high>:<low> 或 bits=<bit> 會將任何引文縮小至位元範圍。

note 包含任意形式的文字。(適用於服務專員之間的交接。)

位置

引用內容會顯示在純文字//留言中。(支援的語言有 // 則留言)。

宣告層級的引用會放在文件註解和項目之間的 // 行，並繫結至後續項目。Rust 中的合法項目，且文件註解仍會附加至該項目。

實作引文會緊接在支援的程式碼上方，並繫結至後續的陳述式或區塊。

引文不得出現在文件註解 (///、//!、/**) 中。如果文件註解區塊中含有引文，Linter 會拒絕。

別名

範例

ID：

struct Timings {
  // @cite(e-edid): sec=2.2 title="EDID Extension Blocks" page=33
  // @alias(e-edid): theirs="vertical addressable line count"
  // @cite(socdb): key=/root/mipi_dsi0/VACTIVE
  height: u16,
}

專案範圍概念：

## Aliases

* `@alias(virtio): theirs="used ring" ours="device-owned ring"`

鍵

theirs 是資訊來源使用的名稱，請照實填寫。必要元素。盡可能不要加上引號，這樣反向 grep 就能找到記錄。

ours 是專案中使用的名稱。專案範圍概念必須使用這項權限。 識別碼的隱含值，會繫結至記錄群組後方的識別碼名稱。

note 包含任意形式的文字。(適用於服務專員之間的交接。)

位置

識別碼，例如暫存器名稱：

  • 與 @cite 相同，位於 ID 聲明之前。
  • 緊接在具有相同標記的 @cite 之後。

專案層級概念：

  • 與 @ref 相同。
  • README：位於「## Aliases」部分。
  • 非擁有的專案檔案：相同的註解區塊，遵循 @ref 並使用相同標記。

項目可以是完整名稱或名稱片段；工具會根據最長比對結果進行替換，且如果同時適用附加記錄和片段規則，系統會優先採用附加記錄。

標準比對模式

人類，輕鬆：

grep -rn '@cite('         # every citation
grep -rn '@cite(virtio)'  # citations of one document
grep -rn '@ref('          # every reference record
grep -rn '@alias('        # every alias record

工具 (錨定) - 來源掃描器： ^[ \t]*(//[/!]?|\*)[ \t]*@(cite|ref|alias)\(([a-z0-9][a-z0-9_-]*)\):

工具 (錨定) - README 掃描器： ^\* `@(ref|alias)\(([a-z0-9][a-z0-9_-]*)\):

來源掃描器也會刻意比對 ///、//! 和區塊註解 * 行，因此 Lint 工具可以偵測到位置錯誤的記錄並拒絕，而不是默默略過。

與格式化工具互動

長記錄行必須通過程式碼格式化工具。

荒漠油廠

我們假設 Fuchsia 自訂項目不會覆寫不穩定的夜間專用 wrap_comments 選項，該選項預設為 false。

rustfmt 不提供任何可保護個別註解的內嵌指令。#[rustfmt::skip] 無法可靠地防止開頭註解換行。

C++

clang-format 根據預設樣式，重新編排長度較長的//留言。

自有專案：將 CommentPragmas: '^ @(cite|ref|alias)\(' 新增至 .clang-format。 請勿使用範圍更廣的 ReflowComments: Never。

非自有專案：將每個參考資料和引文區塊包在 // clang-format off / // clang-format on 防護措施中。

背景：目標和假設

概念模型

參照會將簡短的小寫標記繫結至一個外部文件，且該文件必須是固定版本。引文會將標記和定位器名稱加入該文件。 參照文件的種類會決定適用的定位器詞彙。

「別名」是將本機名稱繫結至特定參照文件所用名稱的記錄。

資訊來源

系統支援下列來源：

  • 分頁文件
    • PDF (原生頁碼) 和同等格式
    • PDF 的 Markdown 轉換，轉換器會在其中插入 <!-- page N --> 標記，讓頁碼在轉換後仍存在。
  • 參考代碼 - 通常是固定在提交或發布標記上的外部樹狀結構
    • C 和 C++
    • 荒漠油廠
    • DeviceTree 繫結
  • 硬體說明文件資料庫
    • 範例：註冊定義資料庫
    • 主要假設：可專屬識別引文目標 (例如暫存器或硬體模組) 的主鍵架構

網頁和其他格式會延後處理，日後再評估是否適用。

用途

  1. 事實查核：人工或 AI 開發人員會根據 Fuchsia 原始碼和引文，逐一閱讀引文位置，並根據來源驗證程式碼。
  2. 子代理通訊：AI 代理會根據引文交換主張。 引文必須包含足夠資訊，可交由其他服務專員處理。
  3. 主題搜尋 (次要) - 人員和 AI 研究人員會調查所有可用的資訊來源，並生成與主題相關的引用資料。

名稱別名

程式碼通常會以不同於參照的方式命名項目： * 供應商用語會替換為包容性用語 * 縮寫會展開，為求明確 * 參照本身不一致

事實查核 (先將程式碼 ID 轉換為文件詞彙，再進行比對) 和反向查閱 (在程式碼集搜尋供應商名稱) 都需要明確的對應。