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. } 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. } 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. } 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". 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. } 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. } 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. } 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]. } 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/
