On 2/7/20 4:06 AM, Markus Armbruster wrote:
Peter Maydell <peter.mayd...@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
