[libvirt] RFC: fixing struct name in public header

[Michal Privoznik]

On 04/12/2017 03:07 PM, Pavel Hrdina wrote:
> On Wed, Apr 12, 2017 at 03:01:35PM +0200, Michal Privoznik wrote:
>> On 04/12/2017 01:31 PM, Daniel P. Berrange wrote:
>>> Take a look at this def from libvirt-domain.h:
>>>
>>> typedef struct _virDomainInterfaceIPAddress virDomainIPAddress;
>>> typedef virDomainIPAddress *virDomainIPAddressPtr;
>>> struct _virDomainInterfaceIPAddress {
>>>     int type;                /* virIPAddrType */
>>>     char *addr;              /* IP address */
>>>     unsigned int prefix;     /* IP address prefix */
>>> };
>>>
>>>
>>> Notice the struct name is different from the typedef names.
>>>
>>> Technically renaming the struct to remove the 'Interface' word
>>> would be an API break.
>>>
>>> On the flip side though we don't expect any apps to use the struct
>>> name, but rather use the typedefs, hence use of '_' in the name.
>>>
>>> We could do what we did with the typed parameter stuff and rename
>>> the struct, but add a
>>>
>>>   #define _virDomainInterfaceIPAddress _virDomainIPAddress
>>>
>>> Any thoughts ?
>>
>> I'd rename it even without the additional #define. APPs should favour
>> the type instead of using struct _virBlah. We have it there because
>> there's no other way to expose the struct members to callers in C.
>
> That's true but it could break some application and libvirt promises not
> to do that, so I'm for the rename including the #define.  We cannot assume
> that it's not used and simply rename it.

I don't think I see how this would break applications. ABI stays the 
same. API - well, if they use struct _virDomainInterfaceIPAddess 
directly, they are going to need to fix that. On the other hand, they 
shouldn't be using it in the first place.

>
> This might be related, but how about marking some our really old API and
> also those wrong names as deprecated or some different compile time warning
> to let developers know that they might want to update their code?

While I would like that, what APIs do you think we should mark as 
deprecated? Because I usually use old APIs when I don't need anything 
fancy (e.g. flags).

Michal