Based-on: 20250711051045.51110-1-jsnow@redhat.com
    [PATCH v6 0/4] qapi: add auto-generated return docs

v2:
 - Applied a few new transformations I had missed.
 - Manually excluded those Markus pointed out as being unhelpful.

Hi, this patch series is a *mostly* mechanical application of QAPI
cross-references to the QAPI/QMP documentation. I exported all
cross-referenceable symbols from the QMP QAPI schema and ran them
through a script that converted any matching words to a cross-reference.

I then used `git add -p` and only added changes that looked reasonable,
omitting many cases of converting common words like "stop",
"transaction", "eject", "String" etc when it wasn't immediately clear
that it was appropriate. I probably missed a few ... in either
direction.

I'd like to ask maintainers for each subsystem to review the changes and
confirm that they make sense. To make it easy for you, here's a link to
each module that was changed, in order:

1/18 acpi
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#acpi
2/18 authz
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#user-authorization
3/18 block
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#block-devices
4/18 crypto
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#cryptography-devices
5/18 dump
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#dump-guest-memory
6/18 job
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#background-jobs
7/18 machine
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#machines
8/18 migration
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#migration
9/18 net
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#net-devices
10/18 pci
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#pci
11/18 QOM
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qemu-object-model-qom
12/18 replay
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#record-replay
13/18 run-state
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#vm-run-state
14/18 sockets
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#socket-data-types
15/18 ui
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#remote-desktop
16/18 virtio
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#virtio-devices
17/18 yank
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#yank-feature
18/18 misc
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qmp-monitor-control
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#ebpf-objects
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qmp-introspection
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc-arm
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc-i386
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc
    https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-stats

A few benefits of doing this:

(1) It makes the docs easier to navigate for users, being able to just
    click to the referred data type / enum / event / command / etc.

(2) It helps prevent bitrot: if the name of a command / event / data
    type / etc changes, the cross-reference will cause the build to
    fail, giving a needed hint that documentation elsewhere needs to be
    updated.

(3) Prompting the maintainers to review the generated HTML documentation
    O:-)

A few hints for maintainers should they wish to try their own hand at
improving the documentation for their subsystems:

 *  Try building docs from your build directory like this:
    > DEBUG=1 pyvenv/bin/sphinx-build -v -j 1 -b html -d docs/manual.p/ ../docs/ docs/manual/;

    Limiting to one thread makes sphinx errors more verbose (and
    helpful), and if you run into rST formatting errors, you can view
    the 'qapi_qapi-schema.ir' artifact in the build directory (DEBUG=1
    causes this to exist) to examine the intermediate rST source code so
    you don't have to fight with the QAPI parsing subsystem to
    understand what happened.

 *  html docs of interest will be in
    docs/manual/interop/qemu-qmp-ref.html

 *  QMP reference index will be at docs/manual/qapi-qmp-index.html

 *  QAPI-specific cross-referencing syntax is documented at
    https://www.qemu.org/docs/master/devel/qapi-domain.html#cross-references

 *  QMP Example syntax is documented towards the bottom of this QAPI
    codegen section:
    https://www.qemu.org/docs/master/devel/qapi-code-gen.html#definition-documentation

John Snow (18):
  qapi: add cross-references to acpi.json
  qapi: add cross-references to authz.json
  qapi: add cross-references to block layer
  qapi: add cross-references to crypto.json
  qapi: add cross-references to dump.json
  qapi: add cross-references to job.json
  qapi: add cross-references to Machine core
  qapi: add cross-references to migration.json
  qapi: add cross-references to net.json
  qapi: add cross-references to pci.json
  qapi: add cross-references to QOM
  qapi: add cross-references to replay.json
  qapi: add cross-references to run-state.json
  qapi: add cross-references to sockets.json
  qapi: add cross-references to ui.json
  qapi: add cross-references to virtio.json
  qapi: add cross-references to yank.json
  qapi: add cross-references to misc modules

 qapi/acpi.json           |   2 +-
 qapi/authz.json          |   2 +-
 qapi/block-core.json     | 188 +++++++++++++++++++--------------------
 qapi/block-export.json   |  36 ++++----
 qapi/block.json          |  14 +--
 qapi/control.json        |   2 +-
 qapi/crypto.json         |   4 +-
 qapi/dump.json           |  12 +--
 qapi/ebpf.json           |   2 +-
 qapi/introspect.json     |  24 ++---
 qapi/job.json            |  71 +++++++--------
 qapi/machine-common.json |  20 ++---
 qapi/machine.json        |  82 ++++++++---------
 qapi/migration.json      |  68 +++++++-------
 qapi/misc-arm.json       |   4 +-
 qapi/misc-i386.json      |   2 +-
 qapi/misc.json           |  12 +--
 qapi/net.json            |   6 +-
 qapi/pci.json            |   2 +-
 qapi/qdev.json           |   4 +-
 qapi/qom.json            |  13 +--
 qapi/replay.json         |  10 +--
 qapi/run-state.json      |  46 +++++-----
 qapi/sockets.json        |   6 +-
 qapi/stats.json          |   8 +-
 qapi/transaction.json    |  12 +--
 qapi/ui.json             |  34 +++----
 qapi/virtio.json         |   8 +-
 qapi/yank.json           |  16 ++--
 29 files changed, 356 insertions(+), 354 deletions(-)

-- 
2.50.0

Queued for 10.1.  Thanks!

John Snow <jsnow@redhat.com> writes:

> Based-on: 20250711051045.51110-1-jsnow@redhat.com
>     [PATCH v6 0/4] qapi: add auto-generated return docs
>
> v2:
>  - Applied a few new transformations I had missed.
>  - Manually excluded those Markus pointed out as being unhelpful.

You missed a few.  Can drop them in my tree.  I also suggested a commit
message amendment.  Can do that in my tree, too.  With that, series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

> Hi, this patch series is a *mostly* mechanical application of QAPI
> cross-references to the QAPI/QMP documentation. I exported all
> cross-referenceable symbols from the QMP QAPI schema and ran them
> through a script that converted any matching words to a cross-reference.
>
> I then used `git add -p` and only added changes that looked reasonable,
> omitting many cases of converting common words like "stop",
> "transaction", "eject", "String" etc when it wasn't immediately clear
> that it was appropriate. I probably missed a few ... in either
> direction.
>
> I'd like to ask maintainers for each subsystem to review the changes and
> confirm that they make sense. To make it easy for you, here's a link to
> each module that was changed, in order:

[...]

> A few benefits of doing this:
>
> (1) It makes the docs easier to navigate for users, being able to just
>     click to the referred data type / enum / event / command / etc.

A *huge* usability win!

> (2) It helps prevent bitrot: if the name of a command / event / data
>     type / etc changes, the cross-reference will cause the build to
>     fail, giving a needed hint that documentation elsewhere needs to be
>     updated.

Can also catch typos.

> (3) Prompting the maintainers to review the generated HTML documentation
>     O:-)

WAT?!?  We're supposed to actually look at the doc we expect our users
to read?

[...]

On Fri, Jul 11, 2025, 5:04 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Based-on: 20250711051045.51110-1-jsnow@redhat.com
> >     [PATCH v6 0/4] qapi: add auto-generated return docs
> >
> > v2:
> >  - Applied a few new transformations I had missed.
> >  - Manually excluded those Markus pointed out as being unhelpful.
>
> You missed a few.  Can drop them in my tree.  I also suggested a commit
> message amendment.  Can do that in my tree, too.  With that, series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>

Please do feel free. I read your reviews and I'm happy with all the
changes, including the commit message changes to highlist the
cross-reference lookup ambiguity problems where they arise.

(Sorry I missed some...)


> > Hi, this patch series is a *mostly* mechanical application of QAPI
> > cross-references to the QAPI/QMP documentation. I exported all
> > cross-referenceable symbols from the QMP QAPI schema and ran them
> > through a script that converted any matching words to a cross-reference.
> >
> > I then used `git add -p` and only added changes that looked reasonable,
> > omitting many cases of converting common words like "stop",
> > "transaction", "eject", "String" etc when it wasn't immediately clear
> > that it was appropriate. I probably missed a few ... in either
> > direction.
> >
> > I'd like to ask maintainers for each subsystem to review the changes and
> > confirm that they make sense. To make it easy for you, here's a link to
> > each module that was changed, in order:
>
> [...]
>
> > A few benefits of doing this:
> >
> > (1) It makes the docs easier to navigate for users, being able to just
> >     click to the referred data type / enum / event / command / etc.
>
> A *huge* usability win!
>
> > (2) It helps prevent bitrot: if the name of a command / event / data
> >     type / etc changes, the cross-reference will cause the build to
> >     fail, giving a needed hint that documentation elsewhere needs to be
> >     updated.
>
> Can also catch typos.
>
> > (3) Prompting the maintainers to review the generated HTML documentation
> >     O:-)
>
> WAT?!?  We're supposed to actually look at the doc we expect our users
> to read?
>
> [...]
>
>

Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@redhat.com> writes:
>
>> Based-on: 20250711051045.51110-1-jsnow@redhat.com
>>     [PATCH v6 0/4] qapi: add auto-generated return docs
>>
>> v2:
>>  - Applied a few new transformations I had missed.
>>  - Manually excluded those Markus pointed out as being unhelpful.
>
> You missed a few.  Can drop them in my tree.  I also suggested a commit
> message amendment.  Can do that in my tree, too.  With that, series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>

One more thing: docs/devel/qapi-code-gen.rst needs an update.
Specifically:

    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.

Let's do that on top.