Skip to contentSkip to conversation

docs/qapi-code-gen: change recommendations for cross-reference syntax

PATCH In review John Snow 2 participants 3 messages Jul 24, 2025 – Jul 31, 2025

lore
Share & tools
lore

John Snow

author
#0 lore raw

PATCH 1/1 docs/qapi-code-gen: change recommendations for cross-reference syntax

The blurb about @foo style references in qapi-code-gen.rst is out of date now, update it.

---
 docs/devel/qapi-code-gen.rst | 11 ++++++++---
 docs/devel/qapi-domain.rst   |  1 +
 2 files changed, 9 insertions(+), 3 deletions(-)
docs/devel/qapi-code-gen.rst +8 -3
index dfdbeac5a5a..51993a6eb0c 100644
@@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup
 should be used.  If you need a single literal ``*``, you will need to
 backslash-escape it.
 
-Use ``@foo`` to reference a name in the schema.  This is an rST
-extension.  It is rendered the same way as ````foo````, but carries
-additional meaning.
+Use ```foo``` to reference a name in the schema and generate a
+cross-reference link. In the event that a cross-reference is ambiguous
+and the manual compilation fails, `QAPI cross-reference roles
+<QAPI-XREF>` can be used to narrow the cross-reference results.
+
+Use ``@foo`` to reference members, which do not currently have a
+cross-reference target. This is an rST extension.  It is rendered the
+same way as ````foo````, but carries additional meaning.
 
 Example::
 
docs/devel/qapi-domain.rst +1 -0
index b71890f6609..8d9fc866bc3 100644
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
 
       :see also: Lorem ipsum, dolor sit amet ...
 
+.. _QAPI-XREF:
 
 Cross-references
 ================
Signature · 1 line
2.50.1
#1 lore raw
Quoted 14 lines · John Snow

The blurb about @foo style references in qapi-code-gen.rst is out of date now, update it.

---
 docs/devel/qapi-code-gen.rst | 11 ++++++++---
 docs/devel/qapi-domain.rst   |  1 +
 2 files changed, 9 insertions(+), 3 deletions(-)
docs/devel/qapi-code-gen.rst +0 -0
index dfdbeac5a5a..51993a6eb0c 100644

docs/devel/qapi-code-gen.rst The usual ****strong****, *\*emphasized\** and ````literal```` markup · line 949

Quoted 10 lines
docs/devel/qapi-code-gen.rst +4 -3
@@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup
 should be used.  If you need a single literal ``*``, you will need to
 backslash-escape it.
 
-Use ``@foo`` to reference a name in the schema.  This is an rST
-extension.  It is rendered the same way as ````foo````, but carries
-additional meaning.
+Use ```foo``` to reference a name in the schema and generate a
+cross-reference link. In the event that a cross-reference is ambiguous
+and the manual compilation fails, `QAPI cross-reference roles
+<QAPI-XREF>` can be used to narrow the cross-reference results.

Two spaces between sentences for consistency, please.

Scratch "manual".

The old text is about @foo, which could legitimately be used for any name. "A name in the schema" was fine. "Was", because we now want foo instead for certain names.

The new text is about foo, which can be used only for certain names:
modules and definitions. So the new text needs to be more precise than "a name in the schema".

The module feature is basically redundant and should not be used. Instead of referencing the beginning of audio.json with audio (shorthand for :qapi:mod:audio), you can (and should) reference its heading with Audio_. Plain reST instead of QAPI-specific extension (strike 1), section structure instead of module structure (strike 2). Let's not to advertize the module feature here.

This leaves definition names.

docs/devel/qapi-code-gen.rst The usual ****strong****, *\*emphasized\** and ````literal```` markup · line 953

Quoted 4 lines
docs/devel/qapi-code-gen.rst +4 -0
+
+Use ``@foo`` to reference members, which do not currently have a
+cross-reference target. This is an rST extension.  It is rendered the
+same way as ````foo````, but carries additional meaning.

I think the main point to make is that for members you need to use @foo. foo doesn't work there.

Here's my try:

Use ```foo``` to reference a definition in the schema. This generates a link to the definition. In the event that such a cross-reference is ambiguous, you can use QAPI cross-reference roles <QAPI-XREF> to disambiguate.

Use @foo to reference a member description within the current definition. This is an rST extension. It is currently rendered the same way as ````foo````, but carries additional meaning.

Quoted 15 lines
docs/devel/qapi-code-gen.rst +0 -0
 Example::
 
docs/devel/qapi-domain.rst +1 -0
index b71890f6609..8d9fc866bc3 100644
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
 
       :see also: Lorem ipsum, dolor sit amet ...
 
+.. _QAPI-XREF:
 
 Cross-references
 ================
#2 lore raw

I took the liberty to post my version as "[PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax" to speed up things. Hope you don't mind.