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

[Eric Blake]

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:

Members:
The members of 'QCryptoBlockOptionsBase' ('format')
The members of 'QCryptoBlockOptionsQCow' when 'format' is "qcow"
('key-secret')

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

signature.asc
Description: OpenPGP digital signature