On Thu, Mar 6, 2025, 7:35 AM Markus Armbruster <armbru@redhat.com> wrote:
> When I eyeballed the previous iteration, I made a few observations[1].
> Let's see what has changed.
>
> } New table of contents shows one level, old two. No objection; the
> } navigation thingie on the left is more useful anyway.
>
> No change. Okay.
>
This is configured in the .rst file, not in code. I just happened to use a
different level in my test document.
For initial merge, I'll probably enable the new generator on QMP only while
I work on namespace support.
> } The new generator elides unreferenced types. Generally good, but two
> } observations:
> }
> } * QapiErrorClass is unreferenced, but its members are mentioned in
> } Errors sections. QapiErrorClass serves as better than nothing error
> } code documentation, but it's gone in the new doc. So this is a minor
> } regression. We can figure out what to do about it later.
> }
> } * Section "QMP errors" is empty in the new doc, because its entire
> } contents is elided. I guess we should elide the section as well, but
> } it's fine to leave that for later.
>
> Unreferenced types are back. Okay; we can elide them later.
>
Yep, it will come along with the inliner later.
> } Old doc shows a definition's since information like any other section.
> } New doc has it in the heading box. Looks prettier and uses much less
> } space. Not sure the heading box is the best place, but it'll do for
> } now, we can always move it around later.
>
> No change.
>
Always happy to take HTML/CSS patches from someone with a strong opinion.
For now, though, ...
> } The new doc's headings use "Struct" or "Union" where the old one uses
> } just "Object". Let's keep "Object", please.
>
> Fixed.
>
> } In the new doc, some member references are no longer rendered as such,
> } e.g. @on-source-error and @on-target-error in BackupCommon's note.
> } Another small regression.
>
> Fixed.
>
> } Union branches are busted in the new generator's output. I know they
> } used to work, so I'm not worried about it.
>
> Fixed: "When TAG-MEMBER is VALUE; The members of BRANCH-TYPE."
>
> The semicolon feels odd. I'd use a colon there. Or put the when at the
> end like the old generator does: "The members of BRANCH-TYPE when
> TAG-MEMBER is VALUE".
>
Easy to change!
> Side effects, I think:
>
> * Members of explicit base types are no longer inlined. Instead: "The
> members of BASE-TYPE."
>
> * Members of explicit command / event argument types are no longer
> inlined. Instead: "The members of ARG-TYPE."
>
> Both fine for the initial version.
>
Yeah, inliner is all or nothing.
> } The new doc shows the return type, the old doc doesn't. Showing it is
> } definitely an improvement, but we need to adjust the doc text to avoid
> } silliness like "Returns: SnapshotInfo – SnapshotInfo".
>
> No change. Can polish on top.
>
I have a patch for this in my kvm forum branch, along with "convert
everything into actual cross-references". Will send afterwards.
> } The new doc shows Arguments / Members, Returns, and Errors in two-column
> } format. Looks nice. But for some reason, the two columns don't align
> } horizontally for Errors like they do for the others. Certainly not a
> } blocker of anything, but we should try to fix it at some point.
>
> No change. Fine to leave for later.
>
Yes, but I did figure out why and I do have a solution planned now. It's
something I had to work around for "The members of..." pointers.
> } The new doc doesn't show non-definition conditionals, as mentioned in
> } the cover letter. It shows definition conditionals twice. Once should
> } suffice.
>
> No change. You asked for advice, and I gave some[2].
>
D'oh!
> } There's probably more, but this is it for now.
>
> Again, this is it for now.
>
>
>
> [1] Message-ID: <87wmds4tpk.fsf@pond.sub.org>
> https://lore.kernel.org/qemu-devel/87wmds4tpk.fsf@pond.sub.org/
>
> [2] Message-ID: <87zfhya0is.fsf@pond.sub.org>
> https://lore.kernel.org/qemu-devel/87zfhya0is.fsf@pond.sub.org/
>
>