@@ -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