Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h

From: Jan Beulich <jbeulich@suse.com>
To: Stefano Stabellini <sstabellini@kernel.org>
Cc: Luca Fancellu <luca.fancellu@arm.com>,
	Bertrand Marquis <bertrand.marquis@arm.com>,
	wei.chen@arm.com, Andrew Cooper <andrew.cooper3@citrix.com>,
	George Dunlap <george.dunlap@citrix.com>,
	Ian Jackson <iwj@xenproject.org>, Julien Grall <julien@xen.org>,
	Wei Liu <wl@xen.org>,
	xen-devel@lists.xenproject.org
Subject: Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h
Date: Thu, 8 Apr 2021 07:59:10 +0200	[thread overview]
Message-ID: <fff2bc3a-701a-51e4-59fe-b26261c6c6bc@suse.com> (raw)
In-Reply-To: <alpine.DEB.2.21.2104071424190.31460@sstabellini-ThinkPad-T480s>

On 07.04.2021 23:26, Stefano Stabellini wrote:
> On Wed, 7 Apr 2021, Jan Beulich wrote:
>> On 07.04.2021 10:42, Luca Fancellu wrote:
>>> Just to be sure that we are in the same page, are you suggesting to modify the name
>>> In this way?
>>>
>>> struct gnttab_cache_flush {
>>> -    union {
>>> +    union xen_gnttab_cache_flush_a {
>>>         uint64_t dev_bus_addr;
>>>         grant_ref_t ref;
>>>     } a;
>>>
>>> Following this kind of pattern: xen_<upper struct name>_<member name> ?
>>
>> While in general I would be fine with this scheme, for field names like
>> "a" or "u" it doesn't fit well imo.
> 
> "a" is a bad name anyway, even for the member. We can take the
> opportunity to find a better name. Almost anything would be better than
> "a". Maybe "refaddr"?

We need to be careful with changing _anything_ in the public interface.
Consumers importing our headers directly (as was e.g. done for the old
linux-2.6.18-xen.hg tree) could break with a field name change as much
as with any other changes to what had been made available to them.

Jan