[PATCH 2/2] Improve hw_params documentation

[Andrew Eikum <aeikum@codeweavers.com>]

[-- Attachment #1: Type: text/plain, Size: 126 bytes --]

---
 include/pcm.h |   14 +++++++++++++-
 src/pcm/pcm.c |   10 +++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)


[-- Attachment #2: 0002-Improve-hw_params-documentation.patch --]
[-- Type: text/x-patch, Size: 2696 bytes --]

diff --git a/include/pcm.h b/include/pcm.h
index be355a9..961c6a0 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -44,8 +44,20 @@ extern "C" {
 
 /** PCM generic info container */
 typedef struct _snd_pcm_info snd_pcm_info_t;
-/** PCM hardware configuration space container */
+
+/** PCM hardware configuration space container
+ *
+ *  snd_pcm_hw_params_t is an opaque structure which contains a set of possible
+ *  PCM hardware configurations. For example, a given instance might include a
+ *  range of buffer sizes, a range of period sizes, and a set of several sample
+ *  formats. Some subset of all possible combinations these sets may be valid,
+ *  but not necessarily any combination will be valid.
+ *
+ *  No validation is done by the various snd_pcm_hw_params_set* functions.
+ *  Instead, #snd_pcm_hw_params will return an error code if the requested
+ *  set of parameters can't be resolved to a single valid configuration. */
 typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t;
+
 /** PCM software configuration container */
 typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t;
 /** PCM status container */
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index dc91f79..ea1afdc 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -809,7 +809,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
  *
  * The configuration is chosen fixing single parameters in this order:
  * first access, first format, first subformat, min channels, min rate, 
- * min period time, max buffer size, min tick time
+ * min period time, max buffer size, min tick time. If no mutually
+ * compatible set of parameters can be chosen, a negative error code
+ * will be returned.
  *
  * After this call, #snd_pcm_prepare() is called automatically and
  * the stream is brought to \c #SND_PCM_STATE_PREPARED state.
@@ -817,6 +819,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
  * The hardware parameters cannot be changed when the stream is
  * running (active). The software parameters can be changed
  * at any time.
+ *
+ * The configuration space will be updated to reflect the chosen
+ * parameters.
  */
 int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
@@ -3183,6 +3188,9 @@ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
  * \brief Fill params with a full configuration space for a PCM
  * \param pcm PCM handle
  * \param params Configuration space
+ *
+ * The configuration space will be filled with all possible ranges
+ * for the PCM device.
  */
 int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {

[-- Attachment #3: Type: text/plain, Size: 0 bytes --]