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

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> 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.
>>
>> 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.

The first sentence makes me expect we'll move these bits to the better
place.  The second then tells me we drop them, without giving a reason.

Suggest:

   Since commit 3264ffced3 (v4.2.0), we have a better place to tell
   users about deprecated and deleted functionality --
   qemu-deprecated.texi.  These "dropped in" remarks all predate it, and
   other feature drops of that vintage are not documented anywhere, so
   moving these to qemu-deprecated.texi makes little sense.  Drop them
   instead.

With something like that
Reviewed-by: Markus Armbruster <armbru@redhat.com>

>>
>> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>> ---
>> 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.