On Fri, Jul 11, 2025, 5:04 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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> > 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? > > [...] > >
