| Message ID | 20240808182636.3657537-2-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: Supply some of the missing member documentation | expand |
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
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!
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?
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!
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
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',
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(-)