Translate AIP-192 proto comment cross-references to rustdoc intra-doc links

[iainmcgin]

Summary

Proto comments following Google's AIP-192 use a cross-reference convention to link between protobuf types, fields, and enum values:

• Fully-qualified: [Book][google.example.v1.Book]
• Scope-relative: [text][Genre.GENRE_SCI_FI] (resolved via protobuf name resolution from the comment's lexical scope)
• Implied: [Book][] (shorthand for [Book][Book])

As of #25, buffa-codegen escapes these so rustdoc renders them as literal text (avoiding broken_intra_doc_links errors). This issue tracks translating them into working rustdoc intra-doc links to the corresponding generated Rust items.

Motivation

There are ~22,000 such cross-references across the googleapis proto corpus, and they appear in the well-known types (any.proto). Resolving them would make generated documentation significantly more navigable. No Rust protobuf code generator currently does this — prost-build escapes them the same way #25 does (see prost-build/src/ast.rs) — so this would be a differentiator.

Approach

buffa-codegen already has the proto-FQN → Rust-path mapping: CodeGenContext::rust_type and rust_type_relative in context.rs, including extern_path handling for cross-crate references (e.g. WKTs in buffa-types). The comment emitter is keyed by FQN, so the lexical scope is known at the call site.

Work items:

• Scope-relative name resolver matching protobuf's lexical scoping rules (current rust_type only accepts leading-dot fully-qualified names)
• Map field and enum-value references to rustdoc's Type::field / Type::VARIANT intra-doc syntax
• Graceful fallback to the Sanitize proto comments for rustdoc in generated code #25 escaping behaviour when the reference target is outside the compilation unit and has no extern_path mapping
• Handle the two-part [display text][ref] form, preserving the display text
• Tests against representative googleapis protos

Out of scope

• Full CommonMark normalization (prost's optional cleanup-markdown feature). The Sanitize proto comments for rustdoc in generated code #25 sanitizer is sufficient for rustdoc safety; this issue is specifically about cross-reference resolution.