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