|
From: | Eric Blake |
Subject: | Re: [PATCH 12/29] qapi: Explicitly put "foo: dropped in n.n" notes into Notes section |
Date: | Fri, 7 Feb 2020 08:23:04 -0600 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
On 2/7/20 4:06 AM, Markus Armbruster wrote:
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 ''.
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
[Prev in Thread] | Current Thread | [Next in Thread] |