[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 18/30] qapi: Delete all the "foo: dropped in n.n" notes
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 18/30] qapi: Delete all the "foo: dropped in n.n" notes |
Date: |
Fri, 14 Feb 2020 16:13:12 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) |
Markus Armbruster <address@hidden> writes:
> 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.
>>
>> 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 <address@hidden>
>>
>> Signed-off-by: Peter Maydell <address@hidden>
>> ---
>> 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.
- [PATCH v2 11/30] qapi/ui.json: Put input-send-event body text in the right place, (continued)
- [PATCH v2 11/30] qapi/ui.json: Put input-send-event body text in the right place, Peter Maydell, 2020/02/13
- [PATCH v2 12/30] qapi/ui.json: Avoid `...' texinfo style quoting, Peter Maydell, 2020/02/13
- [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists, Peter Maydell, 2020/02/13
- [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists, Peter Maydell, 2020/02/13
- [PATCH v2 16/30] qapi: Add blank lines before bulleted lists, Peter Maydell, 2020/02/13
- [PATCH v2 18/30] qapi: Delete all the "foo: dropped in n.n" notes, Peter Maydell, 2020/02/13
- [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists, Peter Maydell, 2020/02/13
- Re: [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists, Markus Armbruster, 2020/02/14
- Re: [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists, Peter Maydell, 2020/02/14
- Re: [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists, Markus Armbruster, 2020/02/14
- Re: [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists, Peter Maydell, 2020/02/14
[PATCH v2 19/30] qapi/qapi-schema.json: Put headers in their own doc-comment blocks, Peter Maydell, 2020/02/13
[PATCH v2 17/30] qapi/migration.json: Replace _this_ with *this*, Peter Maydell, 2020/02/13