Skip to contentSkip to conversation

qapi: Add more cross-references

PATCH Applied Markus Armbruster 3 participants 5 messages Jul 17, 2025 – Jul 29, 2025

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 qapi: Add more cross-references

We recently (merge commit 504632dcc631) enclosed command and type names in backquotes, so they become links in generated HTML. Take care of a few we missed.

---
 qapi/dump.json      | 2 +-
 qapi/machine.json   | 2 +-
 qapi/migration.json | 4 ++--
 qapi/misc-i386.json | 2 +-
 qapi/run-state.json | 2 +-
 qapi/sockets.json   | 2 +-
 6 files changed, 7 insertions(+), 7 deletions(-)
qapi/dump.json +1 -1
index 32c8c1f06e..726b520870 100644
@@ -79,7 +79,7 @@
 #
 # @detach: if true, QMP will return immediately rather than waiting
 #     for the dump to finish.  The user can track progress using
-#     "query-dump".  (since 2.6).
+#     `query-dump`.  (since 2.6).
 #
 # @begin: if specified, the starting physical address.
 #
qapi/machine.json +1 -1
index 6f59f70ca6..038eab281c 100644
@@ -2087,7 +2087,7 @@
 #
 # @deprecated-props: an optional list of properties that are flagged as
 #     deprecated by the CPU vendor.  The list depends on the
-#     CpuModelExpansionType: "static" properties are a subset of the
+#     `CpuModelExpansionType`: "static" properties are a subset of the
 #     enabled-properties for the expanded model; "full" properties are
 #     a set of properties that are deprecated across all models for
 #     the architecture.  (since: 10.1 -- since 9.1 on s390x --).
qapi/migration.json +2 -2
index e08a99bb82..2387c21e9c 100644
@@ -641,7 +641,7 @@
 #
 #     This mode supports VFIO devices provided the user first puts the
 #     guest in the suspended runstate, such as by issuing
-#     guest-suspend-ram to the QEMU guest agent.
+#     `guest-suspend-ram` to the QEMU guest agent.
 #
 #     Best performance is achieved when the memory backend is shared
 #     and the @x-ignore-shared migration capability is set, but this
@@ -1704,7 +1704,7 @@
 #
 # .. admonition:: Notes
 #
-#     1. The 'query-migrate' command should be used to check
+#     1. The `query-migrate` command should be used to check
 #        migration's progress and final result (this information is
 #        provided by the 'status' member).
 #
qapi/misc-i386.json +1 -1
index c8c91a241c..d1ce8caf25 100644
@@ -8,7 +8,7 @@
 #
 # Reset the RTC interrupt reinjection backlog.  Can be used if another
 # mechanism to synchronize guest time is in effect, for example QEMU
-# guest agent's guest-set-time command.
+# guest agent's `guest-set-time` command.
 #
 # Use of this command is only applicable for x86 machines with an RTC,
 # and on other machines will silently return without performing any
qapi/run-state.json +1 -1
index 54ba5c9a3f..4757947ca6 100644
@@ -20,7 +20,7 @@
 # @inmigrate: guest is paused waiting for an incoming migration.  Note
 #     that this state does not tell whether the machine will start at
 #     the end of the migration.  This depends on the command-line -S
-#     option and any invocation of 'stop' or 'cont' that has happened
+#     option and any invocation of `stop` or `cont` that has happened
 #     since QEMU was started.
 #
 # @internal-error: An internal error that prevents further guest
qapi/sockets.json +1 -1
index 82046b0b3a..32fac51728 100644
@@ -143,7 +143,7 @@
 #
 # @str: decimal is for file descriptor number, otherwise it's a file
 #     descriptor name.  Named file descriptors are permitted in
-#     monitor commands, in combination with the 'getfd' command.
+#     monitor commands, in combination with the `getfd` command.
 #     Decimal file descriptors are permitted at startup or other
 #     contexts where no monitor context is active.
 #
Signature · 1 line
2.49.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 5 lines · Markus Armbruster

We recently (merge commit 504632dcc631) enclosed command and type names in backquotes, so they become links in generated HTML. Take care of a few we missed.

Quoted 8 lines
---
 qapi/dump.json      | 2 +-
 qapi/machine.json   | 2 +-
 qapi/migration.json | 4 ++--
 qapi/misc-i386.json | 2 +-
 qapi/run-state.json | 2 +-
 qapi/sockets.json   | 2 +-
 6 files changed, 7 insertions(+), 7 deletions(-)

With regards,
Daniel

Signature · 3 lines
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
Reviewed-by on v1 1/1
#2 lore raw
In reply to Markus Armbruster
Quoted 20 lines · Markus Armbruster

We recently (merge commit 504632dcc631) enclosed command and type names in backquotes, so they become links in generated HTML. Take care of a few we missed.

---
 qapi/dump.json      | 2 +-
 qapi/machine.json   | 2 +-
 qapi/migration.json | 4 ++--
 qapi/misc-i386.json | 2 +-
 qapi/run-state.json | 2 +-
 qapi/sockets.json   | 2 +-
 6 files changed, 7 insertions(+), 7 deletions(-)
qapi/dump.json +0 -0
index 32c8c1f06e..726b520870 100644

qapi/dump.json line 82

Quoted 5 lines
qapi/dump.json +1 -1
@@ -79,7 +79,7 @@
 #
 # @detach: if true, QMP will return immediately rather than waiting
 #     for the dump to finish.  The user can track progress using
-#     "query-dump".  (since 2.6).
+#     `query-dump`.  (since 2.6).

Funny. Offset and in quotes, so it got missed.

qapi/machine.json line 2090

Quoted 13 lines
qapi/dump.json +0 -0
 #
 # @begin: if specified, the starting physical address.
 #
qapi/machine.json +1 -1
index 6f59f70ca6..038eab281c 100644
@@ -2087,7 +2087,7 @@
 #
 # @deprecated-props: an optional list of properties that are flagged as
 #     deprecated by the CPU vendor.  The list depends on the
-#     CpuModelExpansionType: "static" properties are a subset of the
+#     `CpuModelExpansionType`: "static" properties are a subset of the

"What are the odds that a name we want to turn into a reference will be immediately followed by a colon?" 100%, I guess.

qapi/migration.json line 644

Quoted 13 lines
qapi/machine.json +0 -0
 #     enabled-properties for the expanded model; "full" properties are
 #     a set of properties that are deprecated across all models for
 #     the architecture.  (since: 10.1 -- since 9.1 on s390x --).
qapi/migration.json +1 -1
index e08a99bb82..2387c21e9c 100644
@@ -641,7 +641,7 @@
 #
 #     This mode supports VFIO devices provided the user first puts the
 #     guest in the suspended runstate, such as by issuing
-#     guest-suspend-ram to the QEMU guest agent.
+#     `guest-suspend-ram` to the QEMU guest agent.

Missed because it's indented?

qapi/migration.json line 1709

Quoted 11 lines
qapi/migration.json +1 -1
 #
 #     Best performance is achieved when the memory backend is shared
 #     and the @x-ignore-shared migration capability is set, but this
@@ -1704,7 +1704,7 @@
 #
 # .. admonition:: Notes
 #
-#     1. The 'query-migrate' command should be used to check
+#     1. The `query-migrate` command should be used to check
 #        migration's progress and final result (this information is
 #        provided by the 'status' member).

Indent miss.

qapi/misc-i386.json line 11

Quoted 11 lines
qapi/migration.json +0 -0
 #
qapi/misc-i386.json +1 -1
index c8c91a241c..d1ce8caf25 100644
@@ -8,7 +8,7 @@
 #
 # Reset the RTC interrupt reinjection backlog.  Can be used if another
 # mechanism to synchronize guest time is in effect, for example QEMU
-# guest agent's guest-set-time command.
+# guest agent's `guest-set-time` command.

Why'd I miss this one, I wonder?

qapi/run-state.json line 23

Quoted 13 lines
qapi/misc-i386.json +0 -0
 #
 # Use of this command is only applicable for x86 machines with an RTC,
 # and on other machines will silently return without performing any
qapi/run-state.json +1 -1
index 54ba5c9a3f..4757947ca6 100644
@@ -20,7 +20,7 @@
 # @inmigrate: guest is paused waiting for an incoming migration.  Note
 #     that this state does not tell whether the machine will start at
 #     the end of the migration.  This depends on the command-line -S
-#     option and any invocation of 'stop' or 'cont' that has happened
+#     option and any invocation of `stop` or `cont` that has happened

Rare instance of actually *wanting* these to be cross-refs. :)

Quoted 8 lines
qapi/run-state.json +0 -0
 #     since QEMU was started.
 #
 # @internal-error: An internal error that prevents further guest
qapi/sockets.json +0 -0
index 82046b0b3a..32fac51728 100644

qapi/sockets.json line 148

Quoted 7 lines
qapi/sockets.json +1 -1
@@ -143,7 +143,7 @@
 #
 # @str: decimal is for file descriptor number, otherwise it's a file
 #     descriptor name.  Named file descriptors are permitted in
-#     monitor commands, in combination with the 'getfd' command.
+#     monitor commands, in combination with the `getfd` command.
 #     Decimal file descriptors are permitted at startup or other
 #     contexts where no monitor context is active.

Presumably another indent miss.

Quoted 3 lines
qapi/sockets.json +0 -1
 #
--

2.49.0

#3 lore raw
Quoted 16 lines · John Snow
Quoted 15 lines · Markus Armbruster

We recently (merge commit 504632dcc631) enclosed command and type names in backquotes, so they become links in generated HTML. Take care of a few we missed.

---
 qapi/dump.json      | 2 +-
 qapi/machine.json   | 2 +-
 qapi/migration.json | 4 ++--
 qapi/misc-i386.json | 2 +-
 qapi/run-state.json | 2 +-
 qapi/sockets.json   | 2 +-
 6 files changed, 7 insertions(+), 7 deletions(-)
Quoted 12 lines

qapi/dump.json line 82

Quoted 10 lines
qapi/dump.json +1 -1
index 32c8c1f06e..726b520870 100644
@@ -79,7 +79,7 @@
 #
 # @detach: if true, QMP will return immediately rather than waiting
 #     for the dump to finish.  The user can track progress using
-#     "query-dump".  (since 2.6).
+#     `query-dump`.  (since 2.6).

Funny. Offset and in quotes, so it got missed.

I believe your script's heuristic for skipping example blocks skipped too many intented lines. It dealt fine with quotes as far as I can tell.

Quoted 17 lines

qapi/machine.json line 2090

Quoted 13 lines
qapi/dump.json +0 -0
 #
 # @begin: if specified, the starting physical address.
 #
qapi/machine.json +1 -1
index 6f59f70ca6..038eab281c 100644
@@ -2087,7 +2087,7 @@
 #
 # @deprecated-props: an optional list of properties that are flagged as
 #     deprecated by the CPU vendor.  The list depends on the
-#     CpuModelExpansionType: "static" properties are a subset of the
+#     `CpuModelExpansionType`: "static" properties are a subset of the

"What are the odds that a name we want to turn into a reference will be immediately followed by a colon?" 100%, I guess.

Quoted 15 lines

qapi/migration.json line 644

Quoted 13 lines
qapi/machine.json +0 -0
 #     enabled-properties for the expanded model; "full" properties are
 #     a set of properties that are deprecated across all models for
 #     the architecture.  (since: 10.1 -- since 9.1 on s390x --).
qapi/migration.json +1 -1
index e08a99bb82..2387c21e9c 100644
@@ -641,7 +641,7 @@
 #
 #     This mode supports VFIO devices provided the user first puts the
 #     guest in the suspended runstate, such as by issuing
-#     guest-suspend-ram to the QEMU guest agent.
+#     `guest-suspend-ram` to the QEMU guest agent.

Missed because it's indented?

Think so.

Quoted 14 lines

qapi/migration.json line 1709

Quoted 11 lines
qapi/migration.json +1 -1
 #
 #     Best performance is achieved when the memory backend is shared
 #     and the @x-ignore-shared migration capability is set, but this
@@ -1704,7 +1704,7 @@
 #
 # .. admonition:: Notes
 #
-#     1. The 'query-migrate' command should be used to check
+#     1. The `query-migrate` command should be used to check
 #        migration's progress and final result (this information is
 #        provided by the 'status' member).

Indent miss.

Quoted 13 lines

qapi/misc-i386.json line 11

Quoted 11 lines
qapi/migration.json +0 -0
 #
qapi/misc-i386.json +1 -1
index c8c91a241c..d1ce8caf25 100644
@@ -8,7 +8,7 @@
 #
 # Reset the RTC interrupt reinjection backlog.  Can be used if another
 # mechanism to synchronize guest time is in effect, for example QEMU
-# guest agent's guest-set-time command.
+# guest agent's `guest-set-time` command.

Why'd I miss this one, I wonder?

You searched for identifies defined in qapi/. This one's from qga/.

Quoted 7 lines
Quoted 7 lines
qapi/misc-i386.json +0 -0
 #
 # Use of this command is only applicable for x86 machines with an RTC,
 # and on other machines will silently return without performing any
qapi/run-state.json +0 -0
index 54ba5c9a3f..4757947ca6 100644
Quoted 8 lines

qapi/run-state.json line 23

Quoted 6 lines
qapi/run-state.json +1 -1
@@ -20,7 +20,7 @@
 # @inmigrate: guest is paused waiting for an incoming migration.  Note
 #     that this state does not tell whether the machine will start at
 #     the end of the migration.  This depends on the command-line -S
-#     option and any invocation of 'stop' or 'cont' that has happened
+#     option and any invocation of `stop` or `cont` that has happened

Rare instance of actually *wanting* these to be cross-refs. :)

Yes.

Quoted 18 lines
Quoted 8 lines
qapi/run-state.json +0 -0
 #     since QEMU was started.
 #
 # @internal-error: An internal error that prevents further guest
qapi/sockets.json +0 -0
index 82046b0b3a..32fac51728 100644

qapi/sockets.json line 148

Quoted 7 lines
qapi/sockets.json +1 -1
@@ -143,7 +143,7 @@
 #
 # @str: decimal is for file descriptor number, otherwise it's a file
 #     descriptor name.  Named file descriptors are permitted in
-#     monitor commands, in combination with the 'getfd' command.
+#     monitor commands, in combination with the `getfd` command.
 #     Decimal file descriptors are permitted at startup or other
 #     contexts where no monitor context is active.

Presumably another indent miss.

Quoted 5 lines
Quoted 3 lines
qapi/sockets.json +0 -1
 #
--

2.49.0

Thanks!