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

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> 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

Apropos link: 'format' in 'format is "qcow" could be made one.

> 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.

I figure more than a few members would be too noisy.  Which ones to omit
then?  I'm open to ideas, but it needs to be done as a follow-up, to
give us a chance to fix the QMP documentation regression in time for
2.9.

>> +     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 <armbru@redhat.com>
>> ---
>>  scripts/qapi2texi.py | 27 ++++++++++++++++++++-------
>>  1 file changed, 20 insertions(+), 7 deletions(-)
>> 
>
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks!