John Snow <js...@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 <js...@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.
