diff mbox series

[alsa-lib,2/2] control: improve documentation for snd_ctl_elem_info_t

Message ID 20210624171559.14003-2-nihal@nihaljere.xyz
State New
Headers show
Series [alsa-lib,1/2] control: fix typo | expand

Commit Message

Nihal Jere June 24, 2021, 5:16 p.m. UTC 
Signed-off-by: Nihal Jere <nihal@nihaljere.xyz>
---
 include/control.h     | 38 +++++++++++++++++++++++++++++++++++++-
 src/control/control.c |  5 +++++
 2 files changed, 42 insertions(+), 1 deletion(-)
diff mbox series

Patch

diff --git a/include/control.h b/include/control.h
index e386ecec..47e462fd 100644
--- a/include/control.h
+++ b/include/control.h
@@ -152,7 +152,43 @@  typedef struct _snd_ctl_elem_id snd_ctl_elem_id_t;
  */
 typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t;
 
-/** CTL element info container */
+/** CTL element info container
+ *
+ * snd_ctl_elem_info_t can be allocated, cleared, and copied in the same
+ * way as #snd_ctl_elem_value_t, using the analogous functions.
+ *
+ * The ID can be filled in in the same way as for snd_ctl_elem_value_t,
+ * substituting snd_ctl_elem_value_* functions for snd_ctl_elem_info_*
+ * functions. See #snd_ctl_elem_value_t for details.
+ *
+ * The ID or numid must be set before calling snd_ctl_elem_info.
+ *
+ * \code
+ *   snd_ctl_t* ctl;
+ *   snd_ctl_elem_info_t* info;
+ *   snd_ctl_elem_id_t* id;
+ *
+ *   // Allocate info
+ *   snd_ctl_elem_info_malloc(&info);
+ *
+ *   // Obtain id, setup ctl...
+ *
+ *   // set id
+ *   snd_ctl_elem_info_set_id(info, id);
+ *   // OR just set numid (more applicable if you don't have an id)
+ *   snd_ctl_elem_info_set_id(info, snd_ctl_elem_id_get_numid(id));
+ *
+ *   // Get info from driver
+ *   snd_ctl_elem_info(ctl, info);
+ *
+ *   // Do things with info...
+ *
+ *   // Cleanup
+ *   snd_ctl_elem_info_free(info);
+ * \endcode
+ *
+ * The above example excludes error checking for the sake of readability.
+ */
 typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t;
 
 /** CTL element value container.
diff --git a/src/control/control.c b/src/control/control.c
index 3930c7b1..e346fa6b 100644
--- a/src/control/control.c
+++ b/src/control/control.c
@@ -417,6 +417,11 @@  int snd_ctl_elem_list(snd_ctl_t *ctl, snd_ctl_elem_list_t *list)
 
 /**
  * \brief Get CTL element information
+ * 
+ * The object "info" must be allocated and the ID or numid must be filled
+ * prior to calling this function.
+ * See #snd_ctl_elem_info_t to learn more.
+ *
  * \param ctl CTL handle
  * \param info CTL element id/information pointer
  * \return 0 on success otherwise a negative error code