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

[Eric Blake <eblake@redhat.com>]

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