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