Skip to contentSkip to conversation

docs/devel/qapi-code-gen: Update x-ref syntax, minor fixes

PATCH In review Markus Armbruster 2 participants 9 messages Jul 31, 2025 – Aug 8, 2025

lore
Share & tools
lore
#0 lore raw

cover docs/devel/qapi-code-gen: Update x-ref syntax, minor fixes

Markus Armbruster (3):
docs/devel/qapi-code-gen: Add two cross-references we missed docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar docs/devel/qapi-code-gen: Update cross-reference syntax

 docs/devel/qapi-code-gen.rst | 19 ++++++++++++-------
 docs/devel/qapi-domain.rst   |  1 +
 2 files changed, 13 insertions(+), 7 deletions(-)
Signature · 1 line
2.49.0
#1 lore raw

PATCH 1/3 docs/devel/qapi-code-gen: Add two cross-references we missed

Missed in commit 9c66762a601 (docs/qapi-code-gen: add cross-references).

---
 docs/devel/qapi-code-gen.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +2 -2
index dfdbeac5a5..138921b386 100644
@@ -646,9 +646,9 @@ Member 'event' names the event.  This is the event name used in the
 Client JSON Protocol.
 
 Member 'data' defines the event-specific data.  It defaults to an
-empty MEMBERS object.
+empty MEMBERS_ object.
 
-If 'data' is a MEMBERS object, then MEMBERS defines event-specific
+If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
 data just like a struct type's 'data' defines struct type members.
 
 If 'data' is a STRING, then STRING names a complex type whose members
Signature · 1 line
2.49.0
Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH 1/3] docs/devel/qapi-code-gen: Add two cross-references we missed

Quoted 5 lines · Markus Armbruster

Missed in commit 9c66762a601 (docs/qapi-code-gen: add cross-references).

Quoted 9 lines
---
 docs/devel/qapi-code-gen.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +0 -0
index dfdbeac5a5..138921b386 100644

docs/devel/qapi-code-gen.rst Member 'event' names the event. This is the event name used in the · line 649

Quoted 5 lines
docs/devel/qapi-code-gen.rst +1 -1
@@ -646,9 +646,9 @@ Member 'event' names the event.  This is the event name used in the
 Client JSON Protocol.
 
 Member 'data' defines the event-specific data.  It defaults to an
-empty MEMBERS object.
+empty MEMBERS_ object.

Admittedly, I forgot this was valid syntax - it's core to restructuredtext and not a sphinxism, so it only works within the scope of a single document. Quite suitable for this use case, just slightly ashamed I didn't recognize it immediately.

Quoted 9 lines
docs/devel/qapi-code-gen.rst +1 -2
-If 'data' is a MEMBERS object, then MEMBERS defines event-specific
+If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
 data just like a struct type's 'data' defines struct type members.
 
 If 'data' is a STRING, then STRING names a complex type whose members
--

2.49.0

#3 lore raw

PATCH 2/3 docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar

In reply to Markus Armbruster
Fixes 3248c1aaf2db (docs: update the documentation upfront about schema configuration)
---
 docs/devel/qapi-code-gen.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +2 -2
index 138921b386..2cd51729c3 100644
@@ -786,8 +786,8 @@ Configuring the schema
 Syntax::
 
     COND = STRING
-         | { 'all: [ COND, ... ] }
-         | { 'any: [ COND, ... ] }
+         | { 'all': [ COND, ... ] }
+         | { 'any': [ COND, ... ] }
          | { 'not': COND }
 
 All definitions take an optional 'if' member.  Its value must be a
Signature · 1 line
2.49.0
Reviewed-by on v1 2/3
#4 lore raw

Re: [PATCH 2/3] docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammar

Quoted 3 lines · Markus Armbruster
Fixes 3248c1aaf2db (docs: update the documentation upfront about schema configuration)
Quoted 9 lines
---
 docs/devel/qapi-code-gen.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +0 -0
index 138921b386..2cd51729c3 100644

docs/devel/qapi-code-gen.rst Configuring the schema · line 790

Quoted 7 lines
docs/devel/qapi-code-gen.rst +2 -2
@@ -786,8 +786,8 @@ Configuring the schema
 Syntax::
 
     COND = STRING
-         | { 'all: [ COND, ... ] }
-         | { 'any: [ COND, ... ] }
+         | { 'all': [ COND, ... ] }
+         | { 'any': [ COND, ... ] }

Oopsie.

Quoted 6 lines
docs/devel/qapi-code-gen.rst +0 -1
          | { 'not': COND }
 
 All definitions take an optional 'if' member.  Its value must be a
--

2.49.0

#5 lore raw

PATCH 3/3 docs/devel/qapi-code-gen: Update cross-reference syntax

In reply to Markus Armbruster

The new QAPI code generator creates a cross-reference target for each definition documentation. Enabled for the QEMU QMP Reference manual in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference Manual and the QEMU Guest Agent Protocol Reference in commit a6af5443440. We've put these targets to use since, but neglected to update doc comment markup documentation. Do that now.

---
 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 2cd51729c3..d97602f464 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 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-domain-cross-references>` 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.
 
 Example::
 
docs/devel/qapi-domain.rst +1 -0
index fe540d1e40..1924f12d42 100644
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
 
       :see also: Lorem ipsum, dolor sit amet ...
 
+.. _QAPI-domain-cross-references:
 
 Cross-references
 ================
Signature · 1 line
2.49.0
Reviewed-by on v1 3/3
#6 lore raw

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

Quoted 9 lines · Markus Armbruster

The new QAPI code generator creates a cross-reference target for each definition documentation. Enabled for the QEMU QMP Reference manual in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference Manual and the QEMU Guest Agent Protocol Reference in commit a6af5443440. We've put these targets to use since, but neglected to update doc comment markup documentation. Do that now.

No need for this in my opinion, the SOB suffices to say the same thing in my book. I don't insist you remove it, just seems ... oddly pretentious to say I "co-developed" a single paragraph of text ;)

Quoted 2 lines
Quoted 42 lines
---
 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 2cd51729c3..d97602f464 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 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-domain-cross-references>` 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.
 
 Example::
 
docs/devel/qapi-domain.rst +1 -1
index fe540d1e40..1924f12d42 100644
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives::
 
       :see also: Lorem ipsum, dolor sit amet ...
 
+.. _QAPI-domain-cross-references:
 
 Cross-references
 ================
--

2.49.0

#7 lore raw

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

Quoted 9 lines · John Snow
Quoted 8 lines · Markus Armbruster

The new QAPI code generator creates a cross-reference target for each definition documentation. Enabled for the QEMU QMP Reference manual in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference Manual and the QEMU Guest Agent Protocol Reference in commit a6af5443440. We've put these targets to use since, but neglected to update doc comment markup documentation. Do that now.

Quoted 5 lines
Quoted 1 line

No need for this in my opinion, the SOB suffices to say the same thing in my book. I don't insist you remove it, just seems ... oddly pretentious to say I "co-developed" a single paragraph of text ;)

It wasn't obvious to me how to best credit you, so I tried this. The Co-developed-by serves as an explanation why your S-o-b is there.

Please pick one:

1. Do nothing.

2. Delete Co-developed-by.

3. Delete Co-developed-by, your Signed-off-by, add your Reviewed-by.

Quoted 4 lines
Quoted 2 lines

Thanks!

#8 lore raw

Re: [PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax

Quoted 18 lines · Markus Armbruster
Quoted 9 lines · John Snow
Quoted 8 lines · Markus Armbruster

The new QAPI code generator creates a cross-reference target for each definition documentation. Enabled for the QEMU QMP Reference manual in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference Manual and the QEMU Guest Agent Protocol Reference in commit a6af5443440. We've put these targets to use since, but neglected to update doc comment markup documentation. Do that now.

Quoted 5 lines
Quoted 1 line

No need for this in my opinion, the SOB suffices to say the same thing in my book. I don't insist you remove it, just seems ... oddly pretentious to say I "co-developed" a single paragraph of text ;)

Quoted 6 lines

It wasn't obvious to me how to best credit you, so I tried this. The Co-developed-by serves as an explanation why your S-o-b is there.

Please pick one:

1. Do nothing.

You're on vacation now, so by process of elimination, we'll do this ;)

Quoted 12 lines

2. Delete Co-developed-by.

3. Delete Co-developed-by, your Signed-off-by, add your Reviewed-by.

Quoted 4 lines
Quoted 2 lines

Thanks!