[PATCH] qapi: Add more cross-references

[PATCH] qapi: Add more cross-references

[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.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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(-)

diff --git a/qapi/dump.json b/qapi/dump.json
index 32c8c1f06e..726b520870 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -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.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index 6f59f70ca6..038eab281c 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -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 --).
diff --git a/qapi/migration.json b/qapi/migration.json
index e08a99bb82..2387c21e9c 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -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).
 #
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index c8c91a241c..d1ce8caf25 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 54ba5c9a3f..4757947ca6 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -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
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 82046b0b3a..32fac51728 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -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.
 #
-- 
2.49.0

Re: [PATCH] qapi: Add more cross-references

[Daniel P. Berrangé]

On Thu, Jul 17, 2025 at 01:57:51PM +0200, Markus Armbruster wrote:
> 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.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  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(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: 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 :|

Re: [PATCH] qapi: Add more cross-references

[John Snow]

On Thu, Jul 17, 2025 at 7:57 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> 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.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  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(-)
>
> diff --git a/qapi/dump.json b/qapi/dump.json
> index 32c8c1f06e..726b520870 100644
> --- a/qapi/dump.json
> +++ b/qapi/dump.json
> @@ -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.

>  #
>  # @begin: if specified, the starting physical address.
>  #
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 6f59f70ca6..038eab281c 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -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.

>  #     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 --).
> diff --git a/qapi/migration.json b/qapi/migration.json
> index e08a99bb82..2387c21e9c 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -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?

>  #
>  #     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.

>  #
> diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
> index c8c91a241c..d1ce8caf25 100644
> --- a/qapi/misc-i386.json
> +++ b/qapi/misc-i386.json
> @@ -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?

>  #
>  # Use of this command is only applicable for x86 machines with an RTC,
>  # and on other machines will silently return without performing any
> diff --git a/qapi/run-state.json b/qapi/run-state.json
> index 54ba5c9a3f..4757947ca6 100644
> --- a/qapi/run-state.json
> +++ b/qapi/run-state.json
> @@ -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. :)

>  #     since QEMU was started.
>  #
>  # @internal-error: An internal error that prevents further guest
> diff --git a/qapi/sockets.json b/qapi/sockets.json
> index 82046b0b3a..32fac51728 100644
> --- a/qapi/sockets.json
> +++ b/qapi/sockets.json
> @@ -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.

>  #
> --
> 2.49.0

Reviewed-by: John Snow <jsnow@redhat.com>

Re: [PATCH] qapi: Add more cross-references

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Thu, Jul 17, 2025 at 7:57 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> 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.
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  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(-)
>>
>> diff --git a/qapi/dump.json b/qapi/dump.json
>> index 32c8c1f06e..726b520870 100644
>> --- a/qapi/dump.json
>> +++ b/qapi/dump.json
>> @@ -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.

>>  #
>>  # @begin: if specified, the starting physical address.
>>  #
>> diff --git a/qapi/machine.json b/qapi/machine.json
>> index 6f59f70ca6..038eab281c 100644
>> --- a/qapi/machine.json
>> +++ b/qapi/machine.json
>> @@ -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.
>
>>  #     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 --).
>> diff --git a/qapi/migration.json b/qapi/migration.json
>> index e08a99bb82..2387c21e9c 100644
>> --- a/qapi/migration.json
>> +++ b/qapi/migration.json
>> @@ -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.

>>  #
>>  #     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.
>
>>  #
>> diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
>> index c8c91a241c..d1ce8caf25 100644
>> --- a/qapi/misc-i386.json
>> +++ b/qapi/misc-i386.json
>> @@ -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/.

>>  #
>>  # Use of this command is only applicable for x86 machines with an RTC,
>>  # and on other machines will silently return without performing any
>> diff --git a/qapi/run-state.json b/qapi/run-state.json
>> index 54ba5c9a3f..4757947ca6 100644
>> --- a/qapi/run-state.json
>> +++ b/qapi/run-state.json
>> @@ -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.

>>  #     since QEMU was started.
>>  #
>>  # @internal-error: An internal error that prevents further guest
>> diff --git a/qapi/sockets.json b/qapi/sockets.json
>> index 82046b0b3a..32fac51728 100644
>> --- a/qapi/sockets.json
>> +++ b/qapi/sockets.json
>> @@ -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.
>
>>  #
>> --
>> 2.49.0
>
> Reviewed-by: John Snow <jsnow@redhat.com>

Thanks!

Re: [PATCH] qapi: Add more cross-references

[Markus Armbruster]

Queued.  Thanks for the review!