[Top][All Lists]

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

Re: [Qemu-devel] [PATCH for-2.9 27/47] qapi2texi: Generate documentation

From: Eric Blake
Subject: Re: [Qemu-devel] [PATCH for-2.9 27/47] qapi2texi: Generate documentation for variant members
Date: Tue, 14 Mar 2017 14:36:15 -0500
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0

On 03/13/2017 01:18 AM, Markus Armbruster wrote:
> A flat union's branch brings in the members of another type.  Generate
> a suitable reference to that type.
> Example change (qemu-qmp-ref.txt):
>   -- Flat Union: QCryptoBlockOpenOptions
>       The options that are available for all encryption formats when
>       opening an existing volume
>       Members:
>       The members of 'QCryptoBlockOptionsBase'
> +     The members of 'QCryptoBlockOptionsQCow' when 'format' is "qcow"

Relies on the implied knowledge that 'format' is a member of
'QCryptoBlockOptionsBase'. Does that mean references to another type
might usefully want to do a list of member names, to avoid having to
follow the hyperlink, while still leaving the hyperlink when searching
for full details on that member?  As in:

The members of 'QCryptoBlockOptionsBase' ('format')
The members of 'QCryptoBlockOptionsQCow' when 'format' is "qcow"

But it could get noisy (the example here only adds one member; other
unions add lots of members), and I'm also okay if you don't like the
idea or would rather do it as a followup.

> +     The members of 'QCryptoBlockOptionsLUKS' when 'format' is "luks"
>       Since: 2.6
> A simple union's branch adds a member 'data' of some other type.
> Generate documentation for that member.
> Example change (qemu-qmp-ref.txt):
>   -- Simple Union: SocketAddress
>       Captures the address of a socket, which could also be a named file
>       descriptor
>       Members:
>       'type'
>          Not documented
> +     'data: InetSocketAddress' when 'type' is "inet"
> +     'data: UnixSocketAddress' when 'type' is "unix"
> +     'data: VsockSocketAddress' when 'type' is "vsock"
> +     'data: String' when 'type' is "fd"

Looks reasonable.

>       Since: 1.3
> Signed-off-by: Markus Armbruster <address@hidden>
> ---
>  scripts/qapi2texi.py | 27 ++++++++++++++++++++-------
>  1 file changed, 20 insertions(+), 7 deletions(-)

Reviewed-by: Eric Blake <address@hidden>

Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

Attachment: signature.asc
Description: OpenPGP digital signature

reply via email to

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