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

[Markus Armbruster <armbru@redhat.com>]

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).

* query-stats-schemas has a note between arguments and return.  I think
  this demonstrates that the placement algorithm is too simplistic.

Debatable:

* x-debug-query-block-graph has returns after features.  I'd prefer
  returns before features.  No need to debate this now.

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 :)

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.

* 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?