John Snow <js...@redhat.com> writes: > 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 ...
When the best solution is unclear, starting discussion with a simplistic solution is smart. Beats starting with a complicated solution that gets shot down. >> 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. Could a more rigid order help the inliner, too? >> 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? Yes, with 7. Since although a case could also be made for 1. Intro 2. Arguments 3. Return 4. Errors 5. Features 6. Since 7. Details
