1. Patchew
  2. QEMU
  3. [PATCH 0/6] qapi: Supply some of the missing member documentation
  4. View patch

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

Markus Armbruster posted 6 patches 3 months, 2 weeks ago
There is a newer version of this series
[PATCH 1/6] qapi/char: Supply missing member documentation
Posted by Markus Armbruster 3 months, 2 weeks ago 
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)
+#
+# @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
Re: [PATCH 1/6] qapi/char: Supply missing member documentation
Posted by Philippe Mathieu-Daudé 3 months, 2 weeks ago 
Hi Markus,

On 8/8/24 20:26, Markus Armbruster 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)
> +#
> +# @ringbuf: memory ring buffer (since 1.6)
> +#
> +# @memory: synonym for @ringbuf (since 1.5)

What is the rule to sort the members?
Re: [PATCH 1/6] qapi/char: Supply missing member documentation
Posted by Markus Armbruster 3 months, 2 weeks ago 
Philippe Mathieu-Daudé <philmd@linaro.org> writes:

> Hi Markus,
>
> On 8/8/24 20:26, Markus Armbruster 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)
>> +#
>> +# @ringbuf: memory ring buffer (since 1.6)
>> +#
>> +# @memory: synonym for @ringbuf (since 1.5)
>
> What is the rule to sort the members?

I like to keep the member descriptions in the same order as their
definitions in 'data'.

As to the order in 'data': sometimes there's a "natural" order or
grouping, and sometimes alphabetical is best.  However, we too often add
members without giving order a thought, commonly at the end.

Hope this helps!
Re: [PATCH 1/6] qapi/char: Supply missing member documentation
Posted by John Snow 3 months, 1 week ago 
On Fri, Aug 9, 2024 at 5:12 AM Markus Armbruster <armbru@redhat.com> wrote:

> Philippe Mathieu-Daudé <philmd@linaro.org> writes:
>
> > Hi Markus,
> >
> > On 8/8/24 20:26, Markus Armbruster 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)
> >> +#
> >> +# @ringbuf: memory ring buffer (since 1.6)
> >> +#
> >> +# @memory: synonym for @ringbuf (since 1.5)
> >
> > What is the rule to sort the members?
>
> I like to keep the member descriptions in the same order as their
> definitions in 'data'.
>
> As to the order in 'data': sometimes there's a "natural" order or
> grouping, and sometimes alphabetical is best.  However, we too often add
> members without giving order a thought, commonly at the end.
>
> Hope this helps!
>

What Markus says is correct. Some additional clarification:

The order is not part of the API (for QAPI/QMP), so there's no rule.
Matching the doc and definition orders is often the "nicest" but it is not
enforced.

The definition orders usually tend to "grow downwards" like a struct, but
that's only a tendency and not a rule.

Future developments may or may not impose an order; it's often contested.
At times, Marc-Andre and I have desired to establish a canon order for the
purposes of third party APIs, but QAPI as it stands is militant about order
being unimportant and there are no immediate plans to change that, only
rumblings and desires that stand at odds with Markus's desire to keep order
be unimportant.

(Which, to be clear, is not me belly-aching about Markus's excellent
maintainership of QAPI; just pointing out that there is some tension on
that requirement that remains more or less unsettled.)

--js
Re: [PATCH 1/6] qapi/char: Supply missing member documentation
Posted by John Snow 3 months, 2 weeks ago 
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"?


> +#
> +# @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.

ACK

--js
Re: [PATCH 1/6] qapi/char: Supply missing member documentation
Posted by Markus Armbruster 3 months, 2 weeks ago 
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!

Patchew 2.1-devel-b67e4c2

© 2016 - 2024 Red Hat, Inc.