Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Aug 8, 2024 at 2:26 PM Markus Armbruster <armbru@redhat.com> wrote:
>
>> Since we neglect to document several members of ChardevBackendKind,
>> their description in the QEMU QMP Reference manual is "Not
>> documented".  Fix that, and improve the existing member documentation.
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  qapi/char.json   | 44 ++++++++++++++++++++++++++++----------------
>>  qapi/pragma.json |  1 -
>>  2 files changed, 28 insertions(+), 17 deletions(-)
>>
>> diff --git a/qapi/char.json b/qapi/char.json
>> index ef58445cee..8a4a87c95c 100644
>> --- a/qapi/char.json
>> +++ b/qapi/char.json
>> @@ -434,37 +434,49 @@
>>  ##
>>  # @ChardevBackendKind:
>>  #
>> -# @pipe: Since 1.5
>> +# @file: regular files
>>  #
>> -# @udp: Since 1.5
>> +# @serial: serial host device
>>  #
>> -# @mux: Since 1.5
>> +# @parallel: parallel host device
>>  #
>> -# @msmouse: Since 1.5
>> +# @pipe: pipes (since 1.5)
>>  #
>> -# @wctablet: Since 2.9
>> +# @socket: stream socket
>>  #
>> -# @braille: Since 1.5
>> +# @udp: datagram socket (since 1.5)
>>  #
>> -# @testdev: Since 2.2
>> +# @pty: pseudo-terminal
>>  #
>> -# @stdio: Since 1.5
>> +# @null: provides no input, throws away output
>>  #
>> -# @console: Since 1.5
>> +# @mux: (since 1.5)
>>  #
>> -# @spicevmc: Since 1.5
>> +# @msmouse: emulated Microsoft serial mouse (since 1.5)
>>  #
>> -# @spiceport: Since 1.5
>> +# @wctablet: emulated Wacom Penpartner serial tablet (since 2.9)
>>  #
>> -# @qemu-vdagent: Since 6.1
>> +# @braille: Baum Braille device (since 1.5)
>>  #
>> -# @dbus: Since 7.0
>> +# @testdev: device for test-suite control (since 2.2)
>>  #
>> -# @vc: v1.5
>> +# @stdio: standard I/O (since 1.5)
>>  #
>> -# @ringbuf: Since 1.6
>> +# @console: Windows console (since 1.5)
>>  #
>> -# @memory: Since 1.5
>> +# @spicevmc: spice vm channel (since 1.5)
>> +#
>> +# @spiceport: Spice port channel (since 1.5)
>> +#
>> +# @qemu-vdagent: Spice vdagent (since 6.1)
>> +#
>> +# @dbus: D-Bus channel (since 7.0)
>> +#
>> +# @vc: virtual console (since v1.5)
>>
>
> Remove the "v"?

Yes.  Good catch!

>> +#
>> +# @ringbuf: memory ring buffer (since 1.6)
>> +#
>> +# @memory: synonym for @ringbuf (since 1.5)
>>  #
>>  # Features:
>>  #
>> diff --git a/qapi/pragma.json b/qapi/pragma.json
>> index 59fbe74b8c..39a424303b 100644
>> --- a/qapi/pragma.json
>> +++ b/qapi/pragma.json
>> @@ -46,7 +46,6 @@
>>          'BlockdevSnapshotSyncWrapper',
>>          'BlockdevSnapshotWrapper',
>>          'BlockdevVmdkAdapterType',
>> -        'ChardevBackendKind',
>>          'CpuS390Entitlement',
>>          'CpuS390Polarization',
>>          'CpuS390State',
>> --
>> 2.45.0
>>
>
> It'd be nice if these included some kind of cross-reference to
> documentation for the backends in question, but this is better than "(Not
> documented)", so it's not time to be picky.

Same for any enum that's used as union tag?

> ACK

Thank you!