Current API documentation about functions to set/get element value includes unfriendry texts for userspace developers. This commit improves them.
Signed-off-by: Takashi Sakamoto o-takashi@sakamocchi.jp --- src/control/control.c | 117 +++++++++++++++++++++++++++----------------------- 1 file changed, 64 insertions(+), 53 deletions(-)
diff --git a/src/control/control.c b/src/control/control.c index fe9e557..3ce14c2 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -2563,10 +2563,11 @@ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) }
/** - * \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_BOOLEAN CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \return value for the entry + * \brief Get value from given data for a specified channel as an element of + * boolean type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \return Value for the channel. */ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx) { @@ -2576,10 +2577,11 @@ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int }
/** - * \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \return value for the entry + * \brief Get value from given data for a specified channel as an element of + * integer type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \return Value for the channel. */ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx) { @@ -2589,10 +2591,11 @@ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned in }
/** - * \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \return value for the entry + * \brief Get value from given data for a specified channel as an element of + * integer64 type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \return Value for the channel. */ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx) { @@ -2602,10 +2605,11 @@ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsi }
/** - * \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \return value for the entry + * \brief Get value from given data for a specified channel as an element of + * enumerated type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \return Value for the channel. This is an index of name set in the element. */ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx) { @@ -2615,10 +2619,11 @@ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, }
/** - * \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \return value for the entry + * \brief Get value from given data for a specified channel as an element of + * bytes type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \return Value for the channel. */ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx) { @@ -2628,10 +2633,11 @@ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsig }
/** - * \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_BOOLEAN CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \param val value for the entry + * \brief Set value to given data for a specified channel as an element of + * boolean type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \param[in] val Value for the channel. */ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { @@ -2641,10 +2647,11 @@ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, }
/** - * \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \param val value for the entry + * \brief Set value to given data for a specified channel as an element of + * integer type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \param[in] val Value for the channel. */ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { @@ -2654,10 +2661,11 @@ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, }
/** - * \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \param val value for the entry + * \brief Set value to given data for a specified channel as an element of + * integer64 type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \param[in] val Value for the channel. */ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val) { @@ -2667,10 +2675,12 @@ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int id }
/** - * \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \param val value for the entry + * \brief Set value to given data for a specified channel as an element of + * enumerated type. + * \param[in] obj Data of an element. + * \param[in] idx index of channel in the control element + * \param[in] val Value for the channel. This is an index of name set in the + * element. */ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val) { @@ -2680,10 +2690,11 @@ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int i }
/** - * \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value - * \param obj CTL element id/value - * \param idx Entry index - * \param val value for the entry + * \brief Set value to given data for a specified channel as an element of + * bytes type. + * \param[in] obj Data of the element. + * \param[in] idx index of channel in the control element + * \param[in] val Value for the channel. */ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val) { @@ -2693,10 +2704,10 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un }
/** - * \brief Set CTL element #SND_CTL_ELEM_TYPE_BYTES value - * \param obj CTL handle - * \param data Bytes value - * \param size Size in bytes + * \brief Set values to given data as an element of bytes type. + * \param[in] obj Data of the element. + * \param[in] data Pointer to memory block for values. + * \param[in] size The number of bytes included in the memory block. */ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) { @@ -2706,9 +2717,9 @@ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) }
/** - * \brief Get value for a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value - * \param obj CTL element id/value - * \return Pointer to CTL element value + * \brief Get memory block from given data as an element of bytes type. + * \param[in] obj Data of an element. + * \return Pointer to a memory block for values. */ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) { @@ -2717,9 +2728,9 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value - * \param obj CTL element id/value - * \param ptr Pointer to returned CTL element value + * Get value from given data to given pointer as an element of IEC958 type. + * \param[in] obj Data of an element. + * \param[out] ptr Pointer to an IEC958 data. */ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr) { @@ -2728,9 +2739,9 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9 }
/** - * \brief Set value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value - * \param obj CTL element id/value - * \param ptr Pointer to CTL element value + * Set value from given pointer to given data as an element of IEC958 type. + * \param obj Data of an element. + * \param ptr Pointer to an IEC958 data. */ void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr) {