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

[Takashi Iwai]

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.


thanks,

Takashi