| Message ID | 20200206173040.17337-13-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@linaro.org> writes: > A handful of QAPI doc comments include lines like > "ppcemb: dropped in 3.1". The doc comment parser will just > put these into whatever the preceding section was; sometimes > that's "Notes", and sometimes it's some random other section, > as with "NetClientDriver" where the "'dump': dropped in 2.12" > line ends up in the "Since:" section. > > Put all of these explicitly into Notes: sections (either > preexisting or new), with the right indentation, and > standardising on quoting of the symbol with ''. > > In the case of QKeyCode, the generated docs were actively > misformatted: > ac_bookmarks > since 2.10 altgr, altgr_r: dropped in 2.10 > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > qapi/machine.json | 2 +- > qapi/net.json | 6 +++--- > qapi/ui.json | 3 ++- > 3 files changed, 6 insertions(+), 5 deletions(-) > > diff --git a/qapi/machine.json b/qapi/machine.json > index 704b2b0fe31..51ffa96be98 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -20,7 +20,7 @@ > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > -# ppcemb: dropped in 3.1 > +# 'ppcemb': dropped in 3.1 > # > # Since: 3.0 > ## > diff --git a/qapi/net.json b/qapi/net.json > index 109eff71cd4..8fbcbc611b9 100644 > --- a/qapi/net.json > +++ b/qapi/net.json > @@ -447,7 +447,7 @@ > # > # Since: 2.7 > # > -# 'dump': dropped in 2.12 > +# Notes: 'dump': dropped in 2.12 > ## > { 'enum': 'NetClientDriver', > 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', > @@ -464,7 +464,7 @@ > # > # Since: 1.2 > # > -# 'l2tpv3' - since 2.1 > +# Notes: 'l2tpv3' - since 2.1 > ## > { 'union': 'Netdev', > 'base': { 'id': 'str', 'type': 'NetClientDriver' }, > @@ -494,7 +494,7 @@ > # > # Since: 1.2 > # > -# 'vlan': dropped in 3.0 > +# Notes: 'vlan': dropped in 3.0 > ## > { 'struct': 'NetLegacy', > 'data': { > diff --git a/qapi/ui.json b/qapi/ui.json > index 94a07318f55..6da52b81143 100644 > --- a/qapi/ui.json > +++ b/qapi/ui.json > @@ -776,7 +776,6 @@ > # @ac_forward: since 2.10 > # @ac_refresh: since 2.10 > # @ac_bookmarks: since 2.10 > -# altgr, altgr_r: dropped in 2.10 > # > # @muhenkan: since 2.12 > # @katakanahiragana: since 2.12 > @@ -790,6 +789,8 @@ > # > # Since: 1.3.0 > # > +# Notes: - 'altgr': dropped in 2.10 > +# - 'altgr_r': dropped in 2.10 > ## > { 'enum': 'QKeyCode', > 'data': [ 'unmapped', I'm not sure the "dropped in" notes are worth their keep. One, they are too incomplete to be of much use. Two, I think qemu-deprecated.texi is a better home for this kind of information. Easier to consume for the people who need to know. In particular, they can watch the sausage being made by getting themselves added to MAINTAINERS section "Incompatible changes". If we decide we want to document "dropped in" in the schema, then we need to make an effort to reconstruct the missing ones. Also, members names should use @name markup, not 'name'. Cc'ing people ratted out by git-log -S'dropped in'.
On 2/7/20 4:06 AM, Markus Armbruster wrote: > Peter Maydell <peter.maydell@linaro.org> writes: > >> A handful of QAPI doc comments include lines like >> "ppcemb: dropped in 3.1". The doc comment parser will just >> put these into whatever the preceding section was; sometimes >> that's "Notes", and sometimes it's some random other section, >> as with "NetClientDriver" where the "'dump': dropped in 2.12" >> line ends up in the "Since:" section. >> >> Put all of these explicitly into Notes: sections (either >> preexisting or new), with the right indentation, and >> standardising on quoting of the symbol with ''. >> > > I'm not sure the "dropped in" notes are worth their keep. One, they are > too incomplete to be of much use. Two, I think qemu-deprecated.texi is > a better home for this kind of information. Easier to consume for the > people who need to know. In particular, they can watch the sausage > being made by getting themselves added to MAINTAINERS section > "Incompatible changes". We first started adding dropped-in notes at least as early as commit 912092b (part of v2.10.0), with the 'altgr'/'altgr_r' members of QKeyCode. We did not have qemu-deprecated.texi until commit 44c67847 (v3.0.0), so the markings originally made sense. But now that we have a better place for someone to look up "why is my QAPI command not working? oh, qemu-deprecated documents that it was removed, AND tells me details such as why it was useless or what to use in its place", I don't see the need to burden QAPI docs with a mere "this old form with no further documentation used to exist, but you can't use it now, and furthermore this tidbit of information didn't teach you anything useful about what _does_ work with this command" line. > > If we decide we want to document "dropped in" in the schema, then we > need to make an effort to reconstruct the missing ones. Also, members > names should use @name markup, not 'name'. > > Cc'ing people ratted out by git-log -S'dropped in'. I'm all in favor of stopping the use of 'dropped in' in QAPI source files, and sticking to qemu-deprecated.texi instead. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
diff --git a/qapi/machine.json b/qapi/machine.json index 704b2b0fe31..51ffa96be98 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -20,7 +20,7 @@ # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". # -# ppcemb: dropped in 3.1 +# 'ppcemb': dropped in 3.1 # # Since: 3.0 ## diff --git a/qapi/net.json b/qapi/net.json index 109eff71cd4..8fbcbc611b9 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -447,7 +447,7 @@ # # Since: 2.7 # -# 'dump': dropped in 2.12 +# Notes: 'dump': dropped in 2.12 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', @@ -464,7 +464,7 @@ # # Since: 1.2 # -# 'l2tpv3' - since 2.1 +# Notes: 'l2tpv3' - since 2.1 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' }, @@ -494,7 +494,7 @@ # # Since: 1.2 # -# 'vlan': dropped in 3.0 +# Notes: 'vlan': dropped in 3.0 ## { 'struct': 'NetLegacy', 'data': { diff --git a/qapi/ui.json b/qapi/ui.json index 94a07318f55..6da52b81143 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -776,7 +776,6 @@ # @ac_forward: since 2.10 # @ac_refresh: since 2.10 # @ac_bookmarks: since 2.10 -# altgr, altgr_r: dropped in 2.10 # # @muhenkan: since 2.12 # @katakanahiragana: since 2.12 @@ -790,6 +789,8 @@ # # Since: 1.3.0 # +# Notes: - 'altgr': dropped in 2.10 +# - 'altgr_r': dropped in 2.10 ## { 'enum': 'QKeyCode', 'data': [ 'unmapped',
A handful of QAPI doc comments include lines like "ppcemb: dropped in 3.1". The doc comment parser will just put these into whatever the preceding section was; sometimes that's "Notes", and sometimes it's some random other section, as with "NetClientDriver" where the "'dump': dropped in 2.12" line ends up in the "Since:" section. Put all of these explicitly into Notes: sections (either preexisting or new), with the right indentation, and standardising on quoting of the symbol with ''. In the case of QKeyCode, the generated docs were actively misformatted: ac_bookmarks since 2.10 altgr, altgr_r: dropped in 2.10 Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- qapi/machine.json | 2 +- qapi/net.json | 6 +++--- qapi/ui.json | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) -- 2.20.1