On Thu, Mar 6, 2025, 7:35 AM Markus Armbruster <arm...@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....@pond.sub.org> > https://lore.kernel.org/qemu-devel/87wmds4tpk....@pond.sub.org/ > > [2] Message-ID: <87zfhya0is....@pond.sub.org> > https://lore.kernel.org/qemu-devel/87zfhya0is....@pond.sub.org/ > >
