Re: [PATCH v2 18/30] qapi: Delete all the "foo: dropped in n.n" notes

[Markus Armbruster]

Peter Maydell <address@hidden> 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 <address@hidden>
> ---
> 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.