On Thu, Mar 27, 2025 at 5:11 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > This patch changes the qapidoc transmogrifier to generate Return value > > documentation for any command that has a return value but hasn't > > explicitly documented that return value. > > > > Signed-off-by: John Snow <js...@redhat.com> > > Might want to briefly explain placement of the auto-generated return > value documentation. But before we discuss that any further, let's > review the actual changes the the generated docs. > > This patch adds auto-generated return value documentation where we have > none. > > The next patch replaces handwritten by auto-generated return value > documentation where these are at least as good. Moves the return value > docs in some cases. > > First the additions: > > * x-debug-query-block-graph > > Title, intro, features, return > > * query-tpm > > Title, intro, return, example > > * query-dirty-rate > > Title, intro, arguments, return, examples > > * query-vcpu-dirty-limit > > Title, intro, return, example > > * query-vm-generation-id > > Title, return > > * query-memory-size-summary > > Title, intro, example, return > > * query-memory-devices > > Title, intro, return, example > > * query-acpi-ospm-status > > Title, intro, return, example > > * query-stats-schemas > > Title, intro, arguments, note, return > > Undesirable: > > * query-memory-size-summary has returns after the example instead of > before. I figure it needs the TODO hack to separate intro and example > (see announce-self). > Yes > > * query-stats-schemas has a note between arguments and return. I think > this demonstrates that the placement algorithm is too simplistic. > Yeah ... It's just that *glances at length of email* it's been a sensitive topic without a lot of certainty in desire, so I've tried to keep things on the stupid/simple side ... > > Debatable: > > * x-debug-query-block-graph has returns after features. I'd prefer > returns before features. No need to debate this now. > Willing to do this for you if you'd like to enforce it globally. I'd be happy with any mandated order of sections, really. > > Next the movements: > > * x-debug-block-dirty-bitmap-sha256 > > From right before errors to right after > > * blockdev-snapshot-delete-internal-sync > > From right before errors to right after > > * query-xen-replication-status > > From between intro and example to the end > > * query-colo-status > > From between intro and example to the end > > * query-balloon > > From right before errors to right after > > * query-hv-balloon-status-report > > From right before errors to right after > > * query-yank > > From between intro and example to the end > > * add-fd > > From between arguments and errors to between last note and example > > I don't like any of these :) > So it goes ... > > Undesirable: > > * query-xen-replication-status, query-yank, and query-colo-status now > have return after the example instead of before. I figure they now > need the TODO hack to separate intro and example. > Yes > > * add-fd now has a note between arguments and return. Same placement > weakness as for query-stats above. > > Debatable: > > * x-debug-block-dirty-bitmap-sha256, > blockdev-snapshot-delete-internal-sync, query-colo-status, and > query-hv-balloon-status-report now have return after errors instead of > before. I'd prefer before. > > What's the stupidest acceptable placement algorithm? Maybe this one: > > 1. If we have arguments, return goes right after them. > > 2. Else if we have errors, return goes right before them. > > 3. Else if we have features, return goes right before them. > > 4. Else return goes right after the intro (to make this work, we need > a few more TODO hacks). > > Would you be willing to give this a try? > Probably ... So this algorithm seems to imply a preference for this ordering: 1. Intro 2. Arguments 3. Return 4. Errors 5. Features 6. Details Do I have that correct?
