On Tue, Apr 1, 2025 at 2:07 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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? > Oh, absolutely. My series that adds it still assumes a rigid ordering. It just never enforced it. I don't really care what the order even is, just as long as there is one. > > >> 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 > Sure. I tend to exclude it because I personally remove it from the flow anyway, so I don't actually care where it is. If you do, that's fine! > > although a case could also be made for > but you'd prefer the first one, right? I have no interest in making further cases at the moment ;) > > 1. Intro > 2. Arguments > 3. Return > 4. Errors > 5. Features > 6. Since > 7. Details > >
