Re: [PATCH 12/29] qapi: Explicitly put "foo: dropped in n.n" notes into Notes section

[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.
>
> 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 <address@hidden>
> ---
>  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'.