| Message ID | 20200213175647.17628-19-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. > > This tends to render wrongly, more so in the upcoming rST > generator, but sometimes even in the texinfo, as in the case > of QKeyCode: > ac_bookmarks > since 2.10 altgr, altgr_r: dropped in 2.10 > > We now have a better place to tell users about deprecated > and deleted functionality -- qemu-deprecated.texi. > So just remove all these "dropped in" remarks entirely. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > Perhaps qemu-deprecated.texi should be updated -- Markus > said he'd look into that. So this patch is to some extent > a placeholder to get these broken bits of doc comment out > of the way. The appropriate place is appendix "Recently removed features", which appeared in commit 3264ffced3 "dirty-bitmaps: remove deprecated autoload parameter", v4.2.0. We did not document any prior removals then. Perhaps we should systematically document all removals since v4.1.0. I can look into that. I'm not sure documenting older removals now is worth our while. If you think it is, let me know. All the 'dropped in' notes removed in this patch are older. Nothing to do for qemu-deprecated.texi unless we choose to systematically document older removals. > --- > qapi/machine.json | 2 -- > qapi/net.json | 4 ---- > qapi/ui.json | 1 - > 3 files changed, 7 deletions(-) > > diff --git a/qapi/machine.json b/qapi/machine.json > index 704b2b0fe31..6c11e3cf3a4 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -20,8 +20,6 @@ > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > -# ppcemb: dropped in 3.1 > -# > # Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', This is SysEmuTarget. Visible in QMP query-target and query-cpus-fast. > diff --git a/qapi/net.json b/qapi/net.json > index 80dcf0df06e..1cb9a7d782b 100644 > --- a/qapi/net.json > +++ b/qapi/net.json > @@ -446,8 +446,6 @@ > # Available netdev drivers. > # > # Since: 2.7 > -# > -# 'dump': dropped in 2.12 > ## > { 'enum': 'NetClientDriver', > 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', This is enum NetClientDriver. Visible in QMP netdev_add and -netdev. > @@ -493,8 +491,6 @@ > # @opts: device type specific properties (legacy) > # > # Since: 1.2 > -# > -# 'vlan': dropped in 3.0 > ## > { 'struct': 'NetLegacy', > 'data': { This is struct NetLegacy. Visible in -net, I think. > diff --git a/qapi/ui.json b/qapi/ui.json > index 89126da395b..e16e98a060d 100644 > --- a/qapi/ui.json > +++ b/qapi/ui.json > @@ -779,7 +779,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 This is enum QKeyCode. Visible in QMP send-key arguments.
Markus Armbruster <armbru@redhat.com> writes: > 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. >> >> This tends to render wrongly, more so in the upcoming rST >> generator, but sometimes even in the texinfo, as in the case >> of QKeyCode: >> ac_bookmarks >> since 2.10 altgr, altgr_r: dropped in 2.10 >> >> We now have a better place to tell users about deprecated >> and deleted functionality -- qemu-deprecated.texi. >> So just remove all these "dropped in" remarks entirely. The first sentence makes me expect we'll move these bits to the better place. The second then tells me we drop them, without giving a reason. Suggest: Since commit 3264ffced3 (v4.2.0), we have a better place to tell users about deprecated and deleted functionality -- qemu-deprecated.texi. These "dropped in" remarks all predate it, and other feature drops of that vintage are not documented anywhere, so moving these to qemu-deprecated.texi makes little sense. Drop them instead. With something like that Reviewed-by: Markus Armbruster <armbru@redhat.com> >> >> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> >> --- >> Perhaps qemu-deprecated.texi should be updated -- Markus >> said he'd look into that. So this patch is to some extent >> a placeholder to get these broken bits of doc comment out >> of the way. > > The appropriate place is appendix "Recently removed features", which > appeared in commit 3264ffced3 "dirty-bitmaps: remove deprecated autoload > parameter", v4.2.0. We did not document any prior removals then. > > Perhaps we should systematically document all removals since v4.1.0. I > can look into that. > > I'm not sure documenting older removals now is worth our while. If you > think it is, let me know. > > All the 'dropped in' notes removed in this patch are older. Nothing to > do for qemu-deprecated.texi unless we choose to systematically document > older removals.
On Fri, 14 Feb 2020 at 15:13, Markus Armbruster <armbru@redhat.com> wrote: > > Markus Armbruster <armbru@redhat.com> writes: > > > 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. > >> > >> This tends to render wrongly, more so in the upcoming rST > >> generator, but sometimes even in the texinfo, as in the case > >> of QKeyCode: > >> ac_bookmarks > >> since 2.10 altgr, altgr_r: dropped in 2.10 > >> > >> We now have a better place to tell users about deprecated > >> and deleted functionality -- qemu-deprecated.texi. > >> So just remove all these "dropped in" remarks entirely. > > The first sentence makes me expect we'll move these bits to the better > place. The second then tells me we drop them, without giving a reason. > > Suggest: > > Since commit 3264ffced3 (v4.2.0), we have a better place to tell > users about deprecated and deleted functionality -- > qemu-deprecated.texi. These "dropped in" remarks all predate it, and > other feature drops of that vintage are not documented anywhere, so > moving these to qemu-deprecated.texi makes little sense. Drop them > instead. > > With something like that > Reviewed-by: Markus Armbruster <armbru@redhat.com> Yeah, I wrote the commit message on the assumption that we'd be modifying the commit contents to include documenting this stuff somewhere else. If we're happy not to document the feature-drops at all then we can modify the commit message instead. thanks -- PMM
diff --git a/qapi/machine.json b/qapi/machine.json index 704b2b0fe31..6c11e3cf3a4 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -20,8 +20,6 @@ # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". # -# ppcemb: dropped in 3.1 -# # Since: 3.0 ## { 'enum' : 'SysEmuTarget', diff --git a/qapi/net.json b/qapi/net.json index 80dcf0df06e..1cb9a7d782b 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -446,8 +446,6 @@ # Available netdev drivers. # # Since: 2.7 -# -# 'dump': dropped in 2.12 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', @@ -493,8 +491,6 @@ # @opts: device type specific properties (legacy) # # Since: 1.2 -# -# 'vlan': dropped in 3.0 ## { 'struct': 'NetLegacy', 'data': { diff --git a/qapi/ui.json b/qapi/ui.json index 89126da395b..e16e98a060d 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -779,7 +779,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
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. This tends to render wrongly, more so in the upcoming rST generator, but sometimes even in the texinfo, as in the case of QKeyCode: ac_bookmarks since 2.10 altgr, altgr_r: dropped in 2.10 We now have a better place to tell users about deprecated and deleted functionality -- qemu-deprecated.texi. So just remove all these "dropped in" remarks entirely. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- Perhaps qemu-deprecated.texi should be updated -- Markus said he'd look into that. So this patch is to some extent a placeholder to get these broken bits of doc comment out of the way. --- qapi/machine.json | 2 -- qapi/net.json | 4 ---- qapi/ui.json | 1 - 3 files changed, 7 deletions(-) -- 2.20.1