[alsa-devel] [PATCH 06/10] ctl: deprecate APIs to add an element set with a single element

[Takashi Sakamoto]

On 2016年06月14日 20:46, Takashi Iwai wrote:
> On Tue, 14 Jun 2016 13:25:16 +0200,
> Takashi Sakamoto wrote:
>>
>> Hi,
>>
>> On Jun 13 2016 21:51, Takashi Iwai wrote:
>>> On Sun, 12 Jun 2016 10:16:07 +0200,
>>> Takashi Sakamoto wrote:
>>>>
>>>> When comparing old APIs (to add a single element) with new APIs (to add
>>>> an element set), the latter has an benefit to get full identical
>>>> information for a first element in the element set. Furthermore, in
>>>> previous commit, the old APIs become simple wrappers to the new APIs.
>>>> Therefore, there's few intentions to use the old APIs.
>>>>
>>>> This commit deprecates the old APIs to encourage the usage of new APIs.
>>>
>>> In general, it's a bad idea to deprecate an API that has been actually
>>> used, and even a worse idea to give a link warning.  We've done
>>> deprecation for some API functions in the past, and it wasn't a really
>>> smart move.  But it was still justified that they were really unused
>>> API functions.  In this case, however, it's commonly used API.  That's
>>> a big difference.
>>>
>>> I know several system libraries like Gtk+ often deprecating API
>>> functions.  But it's more annoying than useful for developers and
>>> users.  Unless you are masochistic, the likely first reaction after
>>> seeing such a warning is: "upstream sucks again".
>>
>> I just added the link_warning() by immitating these old APIs such as
>> snd_pcm_hwsync(). In short, I assumed that it's a fashion of this
>> userspace library to use compiler/linker functionalities even if it's
>> against usual ways to maintain APIs in userspace libraries.
>
> Yes, we have had such things, and as mentioned, it was a bad idea,
> after all.  The deprecation doesn't help maintaining the stuff.
> You don't need to follow our own bad attitude again.
>
>> (I'm not so strange developer, just foreigner to this project without
>> enough documentations.)
>>
>> For the deprecation, I basically agree with you. But there might be
>> exaggeration about usage of these APIs. They're rarely used, I
>> think. If you know actual application programs to use them, please
>> inform them to me. But I know discussions about the population of
>> these APIs are not a good direction in this case.
>
> Right, it's not the only indication.
>
>> My main intention of this patchset is to add the new APIs. These APIs
>> are completely upper compatible to the old APIs, and have benefits I
>> described. In fact, deleting public APIs is not preferable, but
>> deprecating them and still maintaining sometimes has advantages to
>> motivate users to start using the new ones. For this purpose, I think
>> it better to add 'deprecated' comment into documentations of old APIs.
>
> It depends.  The deprecation and the recommendation are different
> behavior.  The former is needed only when the old API is really
> harmful or doesn't work any longer.  In such a case, giving a link
> warning is helpful so that user can know of it.
>
> Meanwhile, the latter is done everywhere.  It's a programming
> practice, and let users choose a better one.  That being said, it'd be
> good to add recommendation for a better API in the documentation. But
> it's never meant to deprecate some old API function.
>
> Again, deprecation doesn't help much from maintenance POV.  I can
> judge it from my long experiences in both upstream maintainer and
> downstream packager sides.  It may help hardening some serious errors
> if the old API were really bad.  But that's all.

OK. I respect your long work for Linux system and can agree with the 
judgment. Let me drop this patch from patchset I'll post tonight. In the 
patchset, some comments are newly added to indicate the recommendation.

And how about the other parts? Are there any inappropriate codes or 
comments?


Thanks

Takashi Sakamoto