pcm: more better documentation for snd_pcm_poll_descriptors

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

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index 209c5bb0103a7b815c7b91c9e90d1ac5e46111db..e63bbe9e5dbf44aadda4341c5e68625e594dccf7 100644 (file)
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -104,9 +104,13 @@ implementation can be found in the \ref alsa_pcm_rw section.
 The poll or select functions (see 'man 2 poll' or 'man 2 select' for further
 details) allows to receive requests/events from the device while
 an application is waiting on events from other sources (like keyboard, screen,
-network etc.), too. \ref snd_pcm_poll_descriptors can be used to get a file
-descriptor to poll or select on. The implemented
-transfer routines can be found in the \ref alsa_transfers section.
+network etc.), too. \ref snd_pcm_poll_descriptors can be used to get file
+descriptors to poll or select on (note that wait direction might be diferent
+than expected - do not use only returned file descriptors, but handle
+events member as well - see \ref snd_pcm_poll_descriptors function
+description for more details and \ref snd_pcm_poll_descriptors_revents for
+events demangling). The implemented transfer routines can be found in
+the \ref alsa_transfers section.
 
 \subsection pcm_transfer_async Asynchronous notification
 
@@ -1405,7 +1409,9 @@ int snd_pcm_poll_descriptors_count(snd_pcm_t *pcm)
  * does the right "demangling".
  *
  * You can use output from this function as arguments for the select()
- * syscall, too.
+ * syscall, too. Do not forget to translate POLLIN and POLLOUT events to
+ * corresponding FD_SET arrays and demangle events using
+ * \link ::snd_pcm_poll_descriptors_revents() \endlink .
  */
 int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space)
 {