This document recommends formats for:
The formats are optimized for processing by AI agents and scripts, both directly and through tooling. Human readability matters; human authoring convenience is explicitly deprioritized.
Summary:
@cite, references use @ref, aliases use @alias.key=value fields separated by .Records:
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 code embedding records:
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
Grammar details:
Owned project README section:
## 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`
Non-owned project file:
// 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 selects the citation key vocabulary. Required. Valid values:
doc - documentcode - reference codedb - databasex- prefix for experimental key vocabulary setstitle must match the information source's stated title, when available. Required.
version, revision, date must match the information source's metadata, when it exists.
url is a canonical web URL for the information source. Strongly recommended.
pin is a commit hash or release tag. Required for kind=code.
local is the recommended path for a local cache of the information source. Relative to the Fuchsia repository root. AI agents look here first.
Owned projects:
@ref record wrapped in backticks.Non-owned project files:
@ref record, scoped to that file.Default to short unversioned tags. The @ref record has versioning information.
Migrating to a new information source version: edit version=/revision=/date=/pin= in one place, then audit every @cite.
Use version-bearing tags (usb32 alongside usb4) when newer versions don't subsume older versions, and a project may need to reference multiple versions.
// @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
The same bytes work after any comment leader:
// @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"
kinddoc (document)Must contain sec (section) or page.
page is the printed page number; fallback: the PDF sequence number. In converted Markdown, page is the N of the nearest preceding <!-- page N --> marker. (Identical semantics for PDF and converted Markdown.)
title is the section title. Required if sec is present.
q (quote) is a short verbatim phrase (10 words or less) anchoring the exact passage.
codeMust contain file, a path resolved inside the tree pinned by the reference.
Must contain sym (symbol / identifier name) or lines (<line> or <start>-<stop>). Preferably both.
DeviceTree bindings are kind=code citations into the kernel tree.
db (database)key is the primary key identifying the database entry. Required.
bits=<high>:<low> or bits=<bit> narrows any citation to a bit range.
note carries free-form text. (Intended for agent-to-agent handoffs.)
Citations live in plain // comments. (Supported languages have // comments.)
Declaration-level citations go on // lines between the doc comment and the item and bind to the item that follows. Legal in Rust, and the doc comment still attaches to the item.
Implementation citations go on their own line immediately above the code they support and bind to the statement or block that follows.
Citations must not appear in doc comments (///, //!, /**). Linters reject citations in doc comment blocks.
Identifier:
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, }
Project-wide concept:
## Aliases * `@alias(virtio): theirs="used ring" ours="device-owned ring"`
theirs is the name used by the information source - verbatim. Required. Unquoted where possible, so a reverse grep lands on the record.
ours is the name used in our project. Required by project-wide concepts. Implicit for identifiers, bound to the identifier name immediately following the record group.
note carries free-form text. (Intended for agent-to-agent handoffs.)
Identifiers, such as register names:
@cite, preceding the identifier declaration.@cite with the same tag.Project-wide concepts:
@ref.## Aliases section.@ref with the same tag.Entries may be whole names or name fragments; tooling translates by longest-match substitution, and an attached record wins over a fragment rule where both apply.
Humans, casual:
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
Tooling, anchored - source scanner: ^[ \t]*(//[/!]?|\*)[ \t]*@(cite|ref|alias)\(([a-z0-9][a-z0-9_-]*)\):
Tooling, anchored - README scanner: ^\* `@(ref|alias)\(([a-z0-9][a-z0-9_-]*)\):
The source scanner deliberately also matches ///, //!, and block-comment * lines so a linter can detect misplaced records and reject them rather than silently skip them.
Long record lines must survive code formatters.
We assume that Fuchsia customizations will not override the unstable nightly-only wrap_comments option, which defaults to false.
rustfmt offers no inline directive that protects an individual comment. #[rustfmt::skip] does not reliably shield leading comments from wrapping.
clang-format reflows long // comments under the default styles.
Owned project: Add CommentPragmas: '^ @(cite|ref|alias)\(' to .clang-format. Do not use the much broader ReflowComments: Never.
Not owned project: Wrap each block of references and citations in // clang-format off / // clang-format on guards.
A reference binds a short lowercase tag to one external document at one pinned version. A citation names a tag plus a locator into that document. The kind of the referenced document determines which locator vocabulary applies.
An alias is a record binding a local name to the name one specific referenced document uses.
The following sources are supported:
<!-- page N --> markers so page numbers survive conversion.Web pages and other formats are deferred for future consideration.
Code regularly names things differently from its references:
Both fact-checking (translating code identifiers into a document's vocabulary before matching) and reverse lookup (grepping the codebase for a vendor name) depend on the mapping being explicit.