[PATCH] augment snd_pcm_drain() documentation regarding its non-blocking mode usage

[sylvain.bertrand@gmail.com]

augment the documentation regarding the use of the snd_pcm_drain function in
non-blocking mode.

signed-off-by: Sylvain BERTRAND <sylvain.bertrand@legeek.net>
---
 src/pcm/pcm.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
---
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index 1064044c..0d4b2930 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -1311,8 +1311,14 @@ int snd_pcm_drop(snd_pcm_t *pcm)
  * \return 0 on success otherwise a negative error code
  * \retval -ESTRPIPE a suspend event occurred
  *
- * For playback wait for all pending frames to be played and then stop
- * the PCM.
+ * For playback, in blocking mode,  wait for all pending frames to be played
+ * and then stop the PCM.
+ * For playback, in non-blocking mode, will return -EAGAIN if the pcm is still
+ * being drained at the time of the call. A note of caution: the pcm can finish
+ * draining asynchronously from a snd_pcm_draw call. The pcm will be then in
+ * SND_PCM_STATE_SETUP state which means any subsequent calls to snd_pcm_drain
+ * will fail since you cannot switch the pcm to SND_PCM_STATE_DRAINING state
+ * from SND_PCM_STATE_SETUP state.
  * For capture stop PCM permitting to retrieve residual frames.
  *
  * For stopping the PCM stream immediately, use \link ::snd_pcm_drop() \endlink