John Snow <js...@redhat.com> writes: > Based-on: 20250711051045.51110-1-js...@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 <arm...@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? [...]
