在 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

语法详细信息：

参考

示例

自有项目 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（符号 / 标识符名称）或 lines（<line> 或 <start>-<stop>）。最好同时包含这两者。

DeviceTree 绑定是内核树中的 kind=code 引用。

db（数据库）

key 是用于标识数据库条目的主键。必填。

通用

bits=<high>:<low> 或 bits=<bit> 将任何引用缩小到某个位范围。

note 包含自由格式文本。（适用于智能体到智能体的移交。）

展示位置

引用会显示在纯文本//评论中。（支持的语言有 // 条注释。）

声明级引用位于文档注释和项目之间的 // 行上，并绑定到后面的项目。在 Rust 中是合法的，并且文档注释仍然附加到相应项。

实现引用位于其支持的代码正上方的单独一行中，并绑定到后面的语句或块。

引用不得出现在文档注释（///、//!、/**）中。Linter 会拒绝文档注释块中的引用。

别名

示例

标识符：

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 相同，位于标识符声明之前。
  • 紧跟在具有相同标记的 @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 工具可以检测到位置错误的记录并拒绝它们，而不是默默地跳过它们。

与格式化程序的互动

长记录行必须在代码格式化程序中保持不变。

Rust

我们假设 Fuchsia 自定义项不会替换不稳定的仅限每晚构建版本的 wrap_comments 选项，该选项的默认值为 false。

rustfmt 不提供任何可保护单个注释的内嵌指令。#[rustfmt::skip] 无法可靠地防止前导注释换行。

C++

clang-format 在默认样式下重排较长的 // 注释。

自有项目：向 .clang-format 添加了 CommentPragmas: '^ @(cite|ref|alias)\('。 请勿使用范围更广的 ReflowComments: Never。

非自有项目：将每个参考和引用块封装在 // clang-format off / // clang-format on 保护中。

背景：目标和假设

概念模型

引用会将简短的小写标记绑定到某个固定版本的某个外部文档。引用是指向文档的标记名称和定位符。 所引用文档的 kind 决定了适用的定位器词汇。

别名是一种将本地名称绑定到特定引用文档所用名称的记录。

信息来源

支持以下来源：

  • 分页文档
    • PDF（原生页码）和等效格式
    • PDF 的 Markdown 转换，其中转换器会插入 <!-- page N --> 标记，以便在转换后保留页码。
  • 参考代码 - 通常是固定到提交或发布标记的外部树
    • C 和 C++
    • Rust
    • DeviceTree 绑定
  • 硬件文档数据库
    • 示例：注册定义数据库
    • 关键假设：可唯一标识引用目标的（例如寄存器或硬件模块）主键方案

网页和其他格式的媒体文件会延迟处理，以供日后考虑。

用例

  1. 事实核查 - 给定 Fuchsia 源代码及其引用，人工或 AI 开发者会读取每个引用位置，并根据来源验证代码。
  2. 子代理通信 - AI 代理会根据引用交换声明。 引用必须足够独立，以便交给其他代理。
  3. 主题搜索（次要）- 人工和 AI 研究人员调查所有可用的信息来源，并生成一组与主题相关的引用。

名称别名

代码通常会以不同于其引用的方式命名事物： * 供应商术语会被替换为更具包容性的术语 * 首字母缩写词会被展开为清晰起见 * 引用本身存在分歧

事实核查（在匹配之前将代码标识符转换为文档的词汇）和反向查找（在代码库中搜索供应商名称）都依赖于明确的映射。