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

[Jan Beulich <jbeulich@xxxxxxxx>]

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