On Fri, Apr 28, 2023 at 4:24 PM Markus Armbruster <arm...@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 <arm...@redhat.com>
>
Reviewed-by: Ani Sinha <anisi...@redhat.com>
> ---
> docs/devel/qapi-code-gen.rst | 5 +++--
> docs/sphinx/qapidoc.py | 3 +++
> 2 files changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index ff7b74bdb2..6386b58881 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release
> that introduced the
> definition.
>
> An "Example" or "Examples" section is automatically rendered entirely
> -as literal fixed-width text. In other sections, the text is
> -formatted, and rST markup can be used.
> +as literal fixed-width text. "TODO" sections are not rendered at all
> +(they are for developers, not users of QMP). In other sections, the
> +text is formatted, and rST markup can be used.
>
> For example::
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index d791b59492..8f3b9997a1 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc):
> """Return list of doctree nodes for additional sections"""
> nodelist = []
> for section in doc.sections:
> + if section.name and section.name == 'TODO':
> + # Hide TODO: sections
> + continue
> snode = self._make_section(section.name)
> if section.name and section.name.startswith('Example'):
> snode += self._nodes_for_example(section.text)
> --
> 2.39.2
>
>
