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

[Markus Armbruster <armbru@redhat.com>]

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!