qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v31 20/22] Add rx-softmmu


From: Eric Blake
Subject: Re: [PATCH v31 20/22] Add rx-softmmu
Date: Mon, 24 Feb 2020 12:31:21 -0600
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1

On 2/24/20 11:53 AM, Aleksandar Markovic wrote:

Missing mention of the new enum member with a 'since 5.0' designation
in the documentation.


Just want to bring to your attention a point that is not clear to me here.
(forgive me for being an outsider in this area)

No problem - asking questions is how we learn.


Could you please take a look at commit:

bb5ccf225e81d2801c03e63d16c371f0617270e8
<https://github.com/qemu/qemu/commit/bb5ccf225e81d2801c03e63d16c371f0617270e8#diff-d7db5c644ce52a6080e77ef1e7a3811b>

I am not familiar with QAPI doc generator, but shouldn't "Since: 3.0"
cause the same problem as "ppcemb: dropped in 3.1"? If not, why?

That was the opposite direction - in that commit, we were removing stale comments about a member that was no longer present (if the member is not present, the doc engine doesn't know what to attach the tag to, and we now have the better qemu-deprecated.texi file for tracking removals). And even if the removal is not documented, users that depended on it (which should be few, or we would not have removed it), it becomes fairly obvious at the attempted point of use that it no longer works.

But when the member is present, but added later than the original struct, knowing what release the additional members were added is useful documentation when deciding whether support for the new member is present on all versions of qemu you care about, or whether your management code has to consider the case when the member was absent. Yes, you can get the same information from introspection programmatically (in fact, when libvirt has to deal with new additions, that's how it probes whether the addition is there), but having the consistent documentation reminds someone to think about whether checking the introspection is necessary.

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org




reply via email to

[Prev in Thread] Current Thread [Next in Thread]