Re: [PATCH v2 2/4] docs, qapi: generate undocumented return sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Mar 27, 2025 at 5:11 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@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 <jsnow@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