Skip to content

Commit c316a88

Browse files
authored
fix(AIP-192): expand xref resolution rules (#1437)
1 parent 3593fd2 commit c316a88

1 file changed

Lines changed: 16 additions & 3 deletions

File tree

aip/general/0192.md

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,9 +92,21 @@ documentation page containing the diagram as an image.
9292

9393
### Cross-references
9494

95-
Comments **may** "link" to another component (service, method, message, field,
96-
enum, or enum value) by using the fully-qualified name of the element as a
97-
Markdown reference link. For example: `[Book][google.example.v1.Book]`
95+
A comment can "link" to another component (service, method, message, field,
96+
enum, or enum value) as a Markdown reference link. The reference **must** be one
97+
of the following forms:
98+
- The fully-qualified name of the element e.g. `[Book][google.example.v1.Book]`
99+
- A scope-relative reference qualified e.g. `[Sci-Fi genre][Genre.GENRE_SCI_FI]`
100+
- An implied reference e.g. `[Book][]` which equates to `[Book][Book]`
101+
102+
These references are solved as per [name resolution][] rules.
103+
104+
Containing fields names **must not** be used in references. They will not
105+
resolve. The original definition **must** be referenced instead. For example,
106+
`[author][Book.author.family_name]` where `author` is a field of `Book`, will
107+
not resolve, but `[author][Author.family_name]` would.
108+
109+
[name resolution]: https://protobuf.dev/programming-guides/proto3/#name-resolution
98110

99111
### External links
100112

@@ -144,6 +156,7 @@ of inadvertent omissions of the internal content annotation.
144156

145157
## Changelog
146158

159+
- **2024-10-29**: Include cross-reference resolution rules.
147160
- **2023-08-11**: Expand deprecated comment requirement to all components.
148161
- **2021-04-20**: Added guidance for deprecated services and RPCs.
149162
- **2020-04-01**: Added guidance requiring absolute URLs for external links.

0 commit comments

Comments
 (0)