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

[Takashi Sakamoto]

On 2016年06月15日 15:59, Takashi Iwai wrote:
> On Wed, 15 Jun 2016 08:57:09 +0200,
> Takashi Sakamoto wrote:
>>
>> 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.
>
> Great, that's appreciated.
>
>> And how about the other parts? Are there any inappropriate codes or
>> comments?
>
> They are good.  Let's keep them.

Glad ;)


Takashi Sakamoto