qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-devel] [PATCH 2/2] qapi2texi: produce type information


From: Markus Armbruster
Subject: Re: [Qemu-devel] [PATCH 2/2] qapi2texi: produce type information
Date: Fri, 27 Jan 2017 10:38:23 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux)

Marc-André Lureau <address@hidden> writes:

> Add type information to the generated documentation. Without it the
> written documentation is not explicit enough to know how to handle
> the various arguments and members.

This is actually a regression of sorts: the type information we used to
have in qmp-commands.txt got lost when we replaced it by generated
qemu-qmp-ref.*.

> Array types have the following syntax: type[]. Ex: str[].
>
> - Struct, commands and events use the following members syntax:
>
>   { 'member': type, ('foo': str), ... }
>
> Optional members are under parentheses.
>
> A structure with a base type will have 'BaseStruct +' prepended.
>
> - Alternates use the following syntax:
>
>   [ 'foo': type, 'bar': type, ... ]
>
> - Simple unions use the following syntax:
>
>   { 'type': str, 'data': 'type' = [ 'foo': type, 'bar': type... ] }
>
> - Flat unions use the following syntax:
>
>   BaseStruct + 'discriminator' = [ 'foo': type, 'bar': type... ]
>
> Signed-off-by: Marc-André Lureau <address@hidden>

This is a formal language to describe QAPI/QMP from the user's point of
view (the QAPI schema specifies it from the implementor's point of
view).

I intend to implement ideas outlined in my review of "[PATCH v6 05/17]
docs: add master qapi texi files"[*], in particular adding type
information to the argument table.  That will address the stated purpose
of this patch, namely fixing the documentation regression.

We can then compare which fix provides the type information in more
readable form, and whether the additional formal description in your fix
is worth having.

Unfortunately, I need to to some QemuOpts / QAPI work first, because it
blocks features we'd like to have in 2.9.


[*] Message-ID: <address@hidden>
http://lists.gnu.org/archive/html/qemu-devel/2016-12/msg03002.html



reply via email to

[Prev in Thread] Current Thread [Next in Thread]