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

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This patch changes the qapidoc parser to generate stub Return value
> documentation for any command that has a return value but does not have
> a "Returns:" doc section.
>
> The stubs include just the type name, which will be rendered with a
> cross-reference link in the HTML output.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Might want to briefly explain placement of the auto-generated return
value documentation.

The cover letter claims you implemented the placement I suggested:

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 (might require a few more TODO
   hacks to terminate the intro).

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.

Let's check placement.  Skip to the end for a summary of findings.

First the additions (this patch):

* x-debug-query-block-graph

  Title, intro, features, return

  1. doesn't apply, 2. doesn't apply, 3. applies: return should go right
  before features.  It's afterwards.  Unexpected.

* query-tpm

  Title, intro, return, example

  4. applies.  Good.

* query-dirty-rate

  Title, intro, arguments, return, examples

  1. applies.  Good.

* query-vcpu-dirty-limit

  Title, intro, return, example

  4. applies.  Good.

* query-vm-generation-id

  Title, intro, return

  4. applies.  Good.

* query-memory-size-summary

  Title, intro, example, return

  4. applies.  Why is return after example here, and before example
  elsewhere?

  Turns out elsewhere we have Since: between intro and .. qmp-example::
  terminating the intro.  Slighly unusual, Since: more often the last in
  the comment block).

  Except for query-memory-size-summary, which does have Since: at the
  very and, and uses the TODO hack instead to terminate the intro.

  So, the placement algorithm works as intended here.  We just need to
  terminate the intro here as well.

* query-memory-devices

  Title, intro, return, example

  4. applies.  Good.

* query-acpi-ospm-status

  Title, intro, return, example

  4. applies.  Good.

* query-stats-schemas

  Title, intro, arguments, return, note

  1. applies.  Good.

Check placement of moved returns (next patch):

* x-debug-block-dirty-bitmap-sha256

  Title, intro, arguments, features, errors, return

  1. applies: return should go right after arguments.  Its at the end.
  Unexpected.

* query-xen-replication-status

  Title, intro, example, return

  Return after example instead of before.  This is just like
  query-memory-size-summary: placement algorithm works as intended,
  intro needs a terminator.

* query-colo-status

  Title, intro, example, return

  Likewise.

* query-machines

  Title, intro, arguments, return, features, example

  1. applies.  Okay.

* query-balloon

  Title, intro, errors, return, example

  2. applies: return should go right before errors.  It's afterwards.
  Unexpected.

* query-hv-balloon-status-report

  Title, intro, errors, return, example

  Likewise.

* query-yank

  Title, intro, example, return

  Another one just like query-memory-size-summary: placement algorithm
  works as intended, intro needs a terminator.

* query-sev-capabilities

  Title, intro, errors, return, example

  Like query-ballon.

* x-query-virtio-queue-element

  Title, intro, arguments, return, features, example

  1. applies.  Good.


Summary of findings:

1. If we have arguments, return goes right after them.

   Works as intended, except for x-debug-block-dirty-bitmap-sha256.
   Odd.

2. Else if we have errors, return goes right before them.

   You seem to place it afterwards instead.

3. Else if we have features, return goes right before them.

   You seem to place it afterwards instead.

4. Else return goes right after the intro (might require a few more TODO
   hacks to terminate the intro).

   Yes, we need several of them.