Re: [PATCH v2 00/18] QAPI: add cross-references to qapi docs

[Markus Armbruster <armbru@redhat.com>]

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?

[...]