[alsa-devel] [alsa-lib][PATCH] ctl: improve documentation of APIs to add an element set
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@sakamocchi.jp --- src/control/control.c | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-)
diff --git a/src/control/control.c b/src/control/control.c index 85485aa..9bb8021 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -358,7 +358,8 @@ static bool validate_element_member_dimension(snd_ctl_elem_info_t *info) * <dt>-EBUSY * <dd>A element with ID \a id already exists. * <dt>-EINVAL - * <dd>ID has no name, or the number of members is not between 1 to 127. + * <dd>Some arguments include invalid value; i.e. ID field in \a info has no + * name, or the number of members is not between 1 to 127. * <dt>-ENOMEM * <dd>Out of memory, or there are too many user elements. * <dt>-ENXIO @@ -446,7 +447,8 @@ int snd_ctl_elem_add_integer_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info, * <dt>-EBUSY * <dd>A element with ID \a id already exists. * <dt>-EINVAL - * <dd>ID has no name, or the number of members is not between 1 to 127. + * <dd>Some arguments include invalid value; i.e. ID has no name, or the number + * of members is not between 1 to 127. * <dt>-ENOMEM * <dd>Out of memory, or there are too many user elements. * <dt>-ENXIO @@ -530,7 +532,8 @@ int snd_ctl_elem_add_integer64_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info, * <dt>-EBUSY * <dd>A element with ID \a id already exists. * <dt>-EINVAL - * <dd>ID has no name, or the number of members is not between 1 to 127. + * <dd>Some parameters include invalid value; i.e. ID has no name, or the number + * of members is not between 1 to 127. * <dt>-ENOMEM * <dd>Out of memory, or there are too many user elements. * <dt>-ENXIO @@ -591,9 +594,10 @@ int snd_ctl_elem_add_boolean_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info, * <dt>-EBUSY * <dd>A control element with ID \a id already exists. * <dt>-EINVAL - * <dd>\a element_count is not between 1 to 127, or \a items is not at least - * one, or a string in \a labels is empty, or longer than 63 bytes, or total - * length of the labels requires more than 64 KiB storage. + * <dd>Some arguments include invalid value; i.e. \a element_count is not + * between 1 to 127, or \a items is not at least one, or a string in \a + * labels is empty, or longer than 63 bytes, or total length of the labels + * requires more than 64 KiB storage. * <dt>-ENOMEM * <dd>Out of memory, or there are too many user control elements. * <dt>-ENXIO @@ -677,7 +681,8 @@ int snd_ctl_elem_add_enumerated_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info, * <dt>-EBUSY * <dd>A element with ID \a id already exists. * <dt>-EINVAL - * <dd>ID has no name, or the number of members is not between 1 to 511. + * <dd>Some arguments include invalid value; i.e. ID has no name, or the number + * of members is not between 1 to 511. * <dt>-ENOMEM * <dd>Out of memory, or there are too many user elements. * <dt>-ENXIO
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@sakamocchi.jp
Applied, thanks.
Takashi
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@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?
Regards
Takashi Sakamoto
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@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
participants (2)
-
Takashi Iwai -
Takashi Sakamoto