[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: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH for-2.9 27/47] qapi2texi: Generate documentation for variant members |
Date: |
Wed, 15 Mar 2017 08:36:04 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) |
Eric Blake <address@hidden> 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 <address@hidden>
>> ---
>> scripts/qapi2texi.py | 27 ++++++++++++++++++++-------
>> 1 file changed, 20 insertions(+), 7 deletions(-)
>>
>
> Reviewed-by: Eric Blake <address@hidden>
Thanks!
- Re: [Qemu-devel] [PATCH for-2.9 19/47] qapi: Prefer single-quoted strings more consistently, (continued)
- [Qemu-devel] [PATCH for-2.9 14/47] qapi: Prepare for requiring more complete documentation, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 26/47] qapi2texi: Generate reference to base type members, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 46/47] qapi: Make pylint a bit happier, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 27/47] qapi2texi: Generate documentation for variant members, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 17/47] qapi: The #optional tag is redundant, drop, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 37/47] qapi: Fix detection of bogus member documentation, Markus Armbruster, 2017/03/13
- [Qemu-devel] [PATCH for-2.9 03/47] qapi: Back out doc comments added just to please qapi.py, Markus Armbruster, 2017/03/13