From: Zeno Endemann <zeno.endemann@mailbox.org>
Date: Fri, 24 Nov 2023 12:49:49 +0000 (+0100)
Subject: pcm: clarify documentation on some hw params related functions
X-Git-Tag: v1.2.11~22
X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=454638ef30b06a28ed6e42d5d4608498a8874ac1;p=alsa-lib.git

pcm: clarify documentation on some hw params related functions

Closes: https://github.com/alsa-project/alsa-lib/pull/369
Signed-off-by: Zeno Endemann <zeno.endemann@mailbox.org>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
---

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index dc59c50d..0cce108f 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -894,6 +894,7 @@ int snd_pcm_info(snd_pcm_t *pcm, snd_pcm_info_t *info)
  * \param pcm PCM handle
  * \param params Configuration space definition container
  * \return 0 on success otherwise a negative error code
+ * \retval -EBADFD no hardware configuration is set
  */
 int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
@@ -960,6 +961,8 @@ int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 /** \brief Remove PCM hardware configuration and free associated resources
  * \param pcm PCM handle
  * \return 0 on success otherwise a negative error code
+ *
+ * The function will also report success if no configuration is set.
  */
 int snd_pcm_hw_free(snd_pcm_t *pcm)
 {
@@ -3929,6 +3932,11 @@ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
  *
  * The configuration space will be filled with all possible ranges
  * for the PCM device.
+ *
+ * Note that the configuration space may be constrained by the
+ * currently installed configuration on the PCM device. To remove
+ * any constrains, free the configuration with #snd_pcm_hw_free
+ * first.
  */
 int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {