Re: [PATCH 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals

[Juan Quintela]

Markus Armbruster <armbru@redhat.com> wrote:
> QAPI doc comments are for QMP users: they go into the "QEMU QMP
> Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".
>
> The doc comment TODO sections are for somebody else, namely for the
> people who can do: developers.  Do not emit them into the user
> manuals.
>
> This elides the following TODOs:
>
> * SchemaInfoCommand
>
>   # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
>
>   This is a note to developers adding introspection to the guest
>   agent.  It makes no sense to users.
>
> * @query-hotpluggable-cpus
>
>   # TODO: Better documentation; currently there is none.
>
>   This is a reminder for developers.  It doesn't help users.
>
> * @device_add
>
>   # TODO: This command effectively bypasses QAPI completely due to its
>   #       "additional arguments" business.  It shouldn't have been added to
>   #       the schema in this form.  It should be qapified properly, or
>   #       replaced by a properly qapified command.
>
>   Likewise.
>
> Eliding them is an improvement.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Juan Quintela <quintela@redhat.com>