[alsa-devel] [alsa-lib][PATCH] ctl: improve documentation of APIs to add an element set

[Takashi Iwai]

On Sat, 09 Jul 2016 15:18:30 +0200,
Takashi Sakamoto wrote:
> 
> On Jul 9 2016 15:21, Takashi Iwai wrote:
> > On Sat, 09 Jul 2016 03:44:19 +0200,
> > Takashi Sakamoto wrote:
> >>
> >> Currently, documentation of APIs to add an element set describes causes of
> >> errors partly. But it gives an opinion to describe them thoroughly. This
> >> is not good for users.
> >>
> >> This commit changes the documentation so that it partly describes the
> >> causes.
> >>
> >> Signed-off-by: Takashi Sakamoto <o-takashi at sakamocchi.jp>
> > 
> > Applied, thanks.
> 
> Thanks.
> 
> As a rest of issues about the new APIs, I think it better to change
> their names. Currently, I named them by adding '_set' suffix to names of
> old APIs; i.e.
> 'snd_ctl_elem_add_integer' -> 'snd_ctl_elem_add_integer_set'.
> 
> The names give an opinion to users that these APIs are to add something
> to existent control elements. The functionalities of the APIs are add
> some elements to something accessed via CTL handler; practically it's a
> control instance for a sound card, accessed via 'hw' plugin.
> 
> Thus, I think it better to rename them; i.e.
> 'snd_ctl_add_integer_elem_set'. Could I ask your opinion about this?

I prefer a shorter name, but it's a matter of taste.
My wish is only once: never change after the API is released.


thanks,

Takashi