control: Add documentation for snd_ctl_elem_value_*.

Signed-off-by: Tanjeff-N. Moos <tanjeff@cccmz.de>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

include/control.h

@@ -130,7 +130,53 @@ typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t;
 /** CTL element info container */
 typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t;
 
-/** CTL element value container */
+/** CTL element value container
+ *
+ * Contains the value(s) (i.e. members) of a single element. All
+ * values of a given element are of the same type.
+ *
+ * \par Memory management
+ *
+ * To access a value, a snd_ctl_elem_value_t must be allocated using
+ * snd_ctl_elem_value_alloca() or snd_ctl_elem_value_malloc(). When
+ * using the latter, it must be freed again using
+ * snd_ctl_elem_value_free().
+ *
+ * \par Identifier
+ *
+ * Then, the ID must be filled. It is sufficient to fill only the
+ * numid, if known. Otherwise, interface type, device, subdevice,
+ * name, index must all be given.  The following functions can be used
+ * to fill the ID:
+ *
+ * - snd_ctl_elem_value_set_id(): Set the ID. Requires an
+ *   snd_ctl_elem_id_t object.
+ * - snd_ctl_elem_value_set_numid(): Set the numid.
+ * - Or use all of the following:
+ *
+ *   - snd_ctl_elem_value_set_interface()
+ *   - snd_ctl_elem_value_set_device()
+ *   - snd_ctl_elem_value_set_subdevice()
+ *   - snd_ctl_elem_value_set_name()
+ *   - snd_ctl_elem_value_set_index()
+ *
+ * When communicating with the driver (snd_ctl_elem_read(),
+ * snd_ctl_elem_write()), and the numid was given, the interface,
+ * device, ... are filled (even if you set the before). When the numid
+ * is unset (i.e. it is 0), it is filled.
+ *
+ * \par Communicating with the driver
+ *
+ * After the value container was created and filled with the ID of the
+ * desired element, the value(s) can be fetched from the driver (and
+ * thus from the hardware) or written to the driver.
+ *
+ * To fetch a value, use snd_ctl_elem_read(). Thereafter, use the
+ * snd_ctl_elem_value_get_*() functions to obtain the actual value.
+ *
+ * To write a new value, first use a snd_ctl_elem_value_set_*() to set
+ * it, then call snd_ctl_elem_write() to write it to the driver.
+ */
 typedef struct _snd_ctl_elem_value snd_ctl_elem_value_t;
 
 /** CTL event container */
@@ -529,11 +575,20 @@ int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id);
 int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);
 
 size_t snd_ctl_elem_value_sizeof(void);
+
 /** \hideinitializer
- * \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca
- * \param ptr returned pointer
+ * \brief Allocate an invalid #snd_ctl_elem_value_t on the stack.
+ *
+ * Allocate space for a value object on the stack. The allocated
+ * memory need not be freed, because is on the stack.
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
+ * \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address
+ *            of the allocated space will returned here.
  */
 #define snd_ctl_elem_value_alloca(ptr) __snd_alloca(ptr, snd_ctl_elem_value)
+
 int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr);
 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj);
 void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj);

src/control/control.c

@@ -38,32 +38,39 @@ also an interface for notifying about control and structure changes.
 In ALSA control feature, each sound card can have control elements. The elements
 are managed according to below model.
 
- - element set
+ - Element set
+
    - A set of elements with the same attribute (i.e. name, get/put operations).
      Some element sets can be added to a sound card by drivers in kernel and
      userspace applications.
- - element
+
+ - Element
+
    - A control element might be a master volume control, for example, or a
      read-only indicator, such as a sync status. An element has a type (e.g.
-     INTEGER or BOOLEAN) and - depending on the type - min/max values, a step
-     size, a set of possible values (for enums), etc.
- - member
+     SNDRV_CTL_ELEM_TYPE_INTEGER or SNDRV_CTL_ELEM_TYPE_BOOLEAN) and - depending
+     on the type - min/max values, a step size, a set of possible values (for
+     enums), etc.
 
-   - An element includes one or more member(s) to have a value. For
-     example, a stereo volume control element has two members (for
-     left/right).  The members share the same properties (e.g. both
-     volume controls have the same min/max values). The value of each
-     member can be changed by both of userspace applications and
-     drivers in kernel.
+ - Member
+
+   - An element usually includes one or more member(s) to have a value. For
+     example, a stereo volume control element has two members (for left/right),
+     while a mono volume has only one member. The member count can be obtained
+     using snd_ctl_elem_info_get_count(). Elements of type
+     "SNDRV_CTL_ELEM_TYPE_BYTES" or "SNDRV_CTL_ELEM_TYPE_IEC958" have no members
+     at all (and thus no member count), they have just a single value. The
+     members share the same properties (e.g. both volume control members have
+     the same min/max values). The value of each member can be changed by both
+     of userspace applications and drivers in kernel.
 
 
-\section identifying_elements Identifying the Elements
+\section identifying_elements Identifying Elements
 
 Each element has the following identifying properties:
 
   - The numid (a numeric identifier, assigned when the sound card is
     detected, constant while the sound card is kept connected)
-
   - The interface type (e.g. MIXER, CARD or PCM)
   - The device
   - The subdevice
@@ -95,10 +102,10 @@ on. In addition, these functions can report the identifying
 properties. E.g. when the element is addressed using its numid, the
 functions complements the name, index, etc.
 
-To access the values of a control, use the snd_ctl_elem_value*()
-functions.  These allow to get and set the actual values or
-settings. It is also possible to get and set the ID values (such as
-the numid or the name).
+To access the members (i.e. values) of a control, use the
+snd_ctl_elem_value*() functions.  These allow to get and set the
+actual values or settings. It is also possible to get and set the ID
+values (such as the numid or the name).
 
 
 \section element_sets Element Sets
@@ -931,10 +938,19 @@ int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
 }
 
 /**
- * \brief Get CTL element value
- * \param ctl CTL handle
- * \param data Data of an element.
- * \return 0 on success otherwise a negative error code
+ * \brief Get CTL element value.
+ *
+ * Read information from sound card. You must set the ID of the
+ * element before calling this function.
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
+ * \param ctl CTL handle.
+ * \param data The element value. The ID must be set before calling
+ *             the function, and the actual value will be returned
+ *             here.
+ *
+ * \return 0 on success otherwise a negative error code.
  */
 int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
 {
@@ -943,9 +959,16 @@ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
 }
 
 /**
- * \brief Set CTL element value
- * \param ctl CTL handle
- * \param data Data of an element.
+ * \brief Set CTL element value.
+ *
+ * Write new value(s) to the sound card. You must set the ID and the
+ * value of the element before calling this function.
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
+ * \param ctl CTL handle.
+ * \param data The new value.
+ *
  * \retval 0 on success
  * \retval >0 on success when value was changed
  * \retval <0 a negative error code
@@ -2877,9 +2900,16 @@ size_t snd_ctl_elem_value_sizeof()
 }
 
 /**
- * \brief Allocate an invalid #snd_ctl_elem_value_t using standard malloc(3).
- * \param ptr Returned pointer for data of an element.
- * \return 0 on success otherwise negative error code.
+ * \brief Allocate an invalid #snd_ctl_elem_value_t on the heap.
+ *
+ * Allocate space for a value object on the head. The allocated memory
+ * must be freed using snd_ctl_elem_value_free().
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
+ * \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address
+ *            of the allocated space will be returned here.
+ * \return 0 on success, otherwise a negative error code.
  */
 int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
 {
@@ -2891,8 +2921,10 @@ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
 }
 
 /**
- * \brief Frees a previously allocated data of an element.
- * \param obj Data of an element.
+ * \brief Free an #snd_ctl_elem_value_t previously allocated using
+ *        snd_ctl_elem_value_malloc().
+ *
+ * \param obj Pointer to the snd_ctl_elem_value_t.
  */
 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
 {
@@ -2901,6 +2933,9 @@ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
 
 /**
  * \brief Clear given data of an element.
+ *
+ * See snd_ctl_elem_value_t for details.
+ *
  * \param obj Data of an element.
  */
 void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj)
@@ -2909,7 +2944,7 @@ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Copy two data of elements.
+ * \brief Bitwise copy of a snd_ctl_elem_value_t value.
  * \param dst Pointer to destination.
  * \param src Pointer to source.
  */
@@ -2921,9 +2956,10 @@ void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst,
 }
 
 /**
- * \brief Compare one data of an element to the other.
- * \param left Pointer to first data.
- * \param right Pointer to second data.
+ * \brief Compare two snd_ctl_elem_value_t values, bytewise.
+ *
+ * \param left First value.
+ * \param right Second value.
  * \return 0 on match, less than or greater than otherwise, see memcmp(3).
  */
 int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left,
@@ -2934,9 +2970,13 @@ int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left,
 }
 
 /**
- * \brief Get element identifier from given data of an element.
- * \param obj Data of an element.
- * \param ptr Pointer for element identifier.
+ * \brief Get the element identifier from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param ptr Pointer to an identifier object. The identifier is
+ *            stored there.
  */
 void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr)
 {
@@ -2945,9 +2985,12 @@ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_
 }
 
 /**
- * \brief Get element numeric identifier from given data of an element.
- * \param obj Data of an element.
- * \return Element numeric identifier.
+ * \brief Get the identifiers 'numid' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The numid.
  */
 unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj)
 {
@@ -2956,10 +2999,12 @@ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Get interface part of element identifier from given data of an
- *	  element.
- * \param obj Data of an element.
- * \return Interface part of element identifier.
+ * \brief Get the identifiers 'interface' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The interface part of element identifier.
  */
 snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj)
 {
@@ -2968,9 +3013,12 @@ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t
 }
 
 /**
- * \brief Get device part of element identifier from given data of an element.
- * \param obj Data of an element.
- * \return Device part of element identifier.
+ * \brief Get the identifiers 'device' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The device part of element identifier.
  */
 unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj)
 {
@@ -2979,10 +3027,12 @@ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Get subdevice part of element identifier from given data of an
- *	  element.
- * \param obj Data of an element.
- * \return Subdevice part of element identifier.
+ * \brief Get the identifiers 'subdevice' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The subdevice part of element identifier.
  */
 unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj)
 {
@@ -2991,9 +3041,12 @@ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Get name part of element identifier from given data of an element.
- * \param obj Data of an element.
- * \return Name part of element identifier.
+ * \brief Get the identifiers 'name' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The "name" part of element identifier.
  */
 const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj)
 {
@@ -3002,9 +3055,12 @@ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Get index part of element identifier from given data of an element.
- * \param obj Data of an element.
- * \return Index part of element identifier.
+ * \brief Get the identifiers 'index' part from the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \return The index part of element identifier.
  */
 unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj)
 {
@@ -3012,10 +3068,14 @@ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj)
 	return obj->id.index;
 }
 
+
 /**
- * \brief Set element identifier to given data of an element.
- * \param obj Data of an element.
- * \param ptr Pointer to an element identifier.
+ * \brief Set the element identifier within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param ptr The new identifier.
  */
 void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr)
 {
@@ -3024,9 +3084,12 @@ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_
 }
 
 /**
- * \brief Set numeric identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for numeric identifier.
+ * \brief Set the identifiers 'numid' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new numid.
  */
 void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val)
 {
@@ -3035,9 +3098,12 @@ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val)
 }
 
 /**
- * \brief Set interface part of element identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for interface part of element identifier.
+ * \brief Set the identifiers 'interface' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new interface.
  */
 void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val)
 {
@@ -3046,9 +3112,12 @@ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_if
 }
 
 /**
- * \brief Set device part of element identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for device part of element identifier.
+ * \brief Set the identifiers 'device' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new device.
  */
 void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val)
 {
@@ -3057,9 +3126,12 @@ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val)
 }
 
 /**
- * \brief Set subdevice part of element identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for subdevice part of element identifier.
+ * \brief Set the identifiers 'subdevice' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new subdevice.
  */
 void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val)
 {
@@ -3068,9 +3140,12 @@ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int va
 }
 
 /**
- * \brief Set name part of element identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for name part of element identifier,
+ * \brief Set the identifiers 'name' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new name.
  */
 void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val)
 {
@@ -3079,9 +3154,12 @@ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val)
 }
 
 /**
- * \brief Set index part of element identifier to given data of an element.
- * \param obj Data of an element.
- * \param val Value for index part of element identifier.
+ * \brief Set the identifiers 'index' part within the given element value.
+ *
+ * See snd_ctl_elem_value_t for more details.
+ *
+ * \param obj The element value.
+ * \param val The new index.
  */
 void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val)
 {
@@ -3090,12 +3168,16 @@ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val)
 }
 
 /**
- * \brief Get value of a specified member from given data as an element of
- *	  boolean type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \return Value for the member.
- */ 
+ * \brief Get an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It
+ * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref
+ * control for more details.
+ *
+ * \param obj The element value object
+ * \param idx The index of the member.
+ * \return The members value.
+ */
 int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx)
 {
 	assert(obj);
@@ -3104,12 +3186,16 @@ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int
 }
 
 /**
- * \brief Get value of a specified member from given data as an element of
- *	  integer type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \return Value for the member.
- */ 
+ * \brief Get an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It
+ * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref
+ * control for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \return The members value.
+ */
 long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx)
 {
 	assert(obj);
@@ -3118,12 +3204,16 @@ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned in
 }
 
 /**
- * \brief Get value of a specified member from given data as an element of
- *	  integer64 type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \return Value for the member.
- */ 
+ * \brief Get an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It
+ * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref
+ * control for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \return The members value.
+ */
 long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx)
 {
 	assert(obj);
@@ -3132,12 +3222,16 @@ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsi
 }
 
 /**
- * \brief Get value of a specified member from given data as an element of
- *	  enumerated type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \return Value for the member. This is an index of name set in the element.
- */ 
+ * \brief Get an element members value.
+ *
+ * Use this function if the element is of type
+ * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It returns the index of the active item. See
+ * \ref snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the requested member.
+ * \return The index of the active item.
+ */
 unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx)
 {
 	assert(obj);
@@ -3146,12 +3240,16 @@ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj,
 }
 
 /**
- * \brief Get value of a specified member from given data as an element of
- *	  bytes type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \return Value for the member.
- */ 
+ * \brief Get an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It
+ * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref
+ * control for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \return The members value.
+ */
 unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx)
 {
 	assert(obj);
@@ -3160,12 +3258,16 @@ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsig
 }
 
 /**
- * \brief Set value of a specified member to given data as an element of
- *	  boolean type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \param val Value for the member.
- */ 
+ * \brief Set an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It
+ * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control
+ * for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \param val The new value.
+ */
 void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
 {
 	assert(obj);
@@ -3174,12 +3276,16 @@ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx,
 }
 
 /**
- * \brief Set value of a specified member to given data as an element of
- *	  integer type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \param val Value for the member.
- */ 
+ * \brief Set an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It
+ * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control
+ * for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \param val The new value.
+ */
 void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
 {
 	assert(obj);
@@ -3188,12 +3294,16 @@ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx,
 }
 
 /**
- * \brief Set value of a specified member to given data as an element of
- *	  integer64 type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \param val Value for the member.
- */ 
+ * \brief Set an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It
+ * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control
+ * for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \param val The new value.
+ */
 void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val)
 {
 	assert(obj);
@@ -3202,12 +3312,16 @@ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int id
 }
 
 /**
- * \brief Set value of a specified member to given data as an element of
- * 	  enumerated type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \param val Value for the member.
- */ 
+ * \brief Set an element members value.
+ *
+ * Use this function if the element is of type
+ * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It activates the specified item. See \ref
+ * snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the requested member.
+ * \param val The new index of the item to be activated.
+ */
 void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val)
 {
 	assert(obj);
@@ -3216,12 +3330,16 @@ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int i
 }
 
 /**
- * \brief Set value for a specified member to given data as an element of byte
- *	  type.
- * \param obj Data of an element.
- * \param idx Index of member in the element.
- * \param val Value for the member.
- */ 
+ * \brief Set an element members value.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It
+ * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control
+ * for more details.
+ *
+ * \param obj The element value object.
+ * \param idx The index of the member.
+ * \param val The new value.
+ */
 void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val)
 {
 	assert(obj);
@@ -3230,10 +3348,17 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un
 }
 
 /**
- * \brief Set values to given data as an element of bytes type.
- * \param obj Data of an element.
- * \param data Pointer for byte array.
- * \param size The number of bytes included in the memory block.
+ * \brief Replace the data stored within the element.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It
+ * replaces the data stored in the element. Note that "bytes" elements don't
+ * have members. They have only one single block of data.
+ *
+ * See \ref snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \param data Pointer to the new data.
+ * \param size The size of the new data, in bytes.
  */
 void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size)
 {
@@ -3243,10 +3368,17 @@ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size)
 }
 
 /**
- * \brief Get memory block from given data as an element of bytes type.
- * \param obj Data of an element.
- * \return Pointer for byte array.
- */ 
+ * \brief Get the data stored within the element.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It
+ * returns the data stored in the element. Note that "bytes" elements don't have
+ * members. They have only one single block of data.
+ *
+ * See \ref snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \return Pointer to the elements data.
+ */
 const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
 {
 	assert(obj);
@@ -3254,11 +3386,17 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
 }
 
 /**
- * \brief Get value from given data to given pointer as an element of IEC958
- *	  type.
- * \param obj Data of an element.
- * \param ptr Pointer to IEC958 data.
- */ 
+ * \brief Get an elements IEC958 data.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958.  Note that
+ * "IEC958" elements don't have members. They have only one single
+ * IEC958 information block.
+ *
+ * See \ref snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \param ptr Pointer to an IEC958 structure. The data is stored there.
+ */
 void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr)
 {
 	assert(obj && ptr);
@@ -3266,11 +3404,17 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9
 }
 
 /**
- * \brief Set value from given pointer to given data as an element of IEC958
- *	  type.
- * \param obj Data of an element.
- * \param ptr Pointer to IEC958 data.
- */ 
+ * \brief Set an elements IEC958 data.
+ *
+ * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958.  Note
+ * that "IEC958" elements don't have members. They have only one single IEC958
+ * information block.
+ *
+ * See \ref snd_ctl_elem_value_t and \ref control for more details.
+ *
+ * \param obj The element value object.
+ * \param ptr Pointer to the new IEC958 data.
+ */
 void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr)
 {
 	assert(obj && ptr);