From: Jaroslav Kysela <perex@perex.cz>
Date: Mon, 8 Mar 2021 14:24:31 +0000 (+0100)
Subject: control: better docs for snd_ctl_elem_id_compare()
X-Git-Tag: v1.2.5~92
X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=266618088aa6e17672ffb08a110b2fff2e2f7ad2;p=alsa-lib.git

control: better docs for snd_ctl_elem_id_compare()

Signed-off-by: Jaroslav Kysela <perex@perex.cz>
---

diff --git a/src/control/control.c b/src/control/control.c
index 4c7d80fd..197d4f52 100644
--- a/src/control/control.c
+++ b/src/control/control.c
@@ -1822,7 +1822,16 @@ void snd_ctl_elem_id_copy(snd_ctl_elem_id_t *dst, const snd_ctl_elem_id_t *src)
  * \brief compare one #snd_ctl_elem_id_t to another
  * \param id1 pointer to first id
  * \param id2 pointer to second id
- * \retval zero when values are identical, -1 first id
+ * \retval zero when values are identical, other value on a difference (like strcmp)
+ *
+ * This comparison ignores the numid part. The numid comparison can be easily
+ * implemented using snd_ctl_elem_id_get_numid() calls.
+ *
+ * The identifier fields are compared in this order: interface, device,
+ * subdevice, name, index.
+ *
+ * The return value can be used for sorting like qsort(). It gives persistent
+ * results.
  */
 int snd_ctl_elem_id_compare(snd_ctl_elem_id_t *id1, const snd_ctl_elem_id_t *id2)
 {