pcm: clarify documentation of poll descriptor usage

pcm: clarify documentation of poll descriptor usage

This is based on my understanding of the intended behavior, the
test/pcm.c example code, as well as the github pull request
discussion (#370).

There needs to be more clarifiaction regarding the exact semantics
of the value of the revents output parameter of
snd_pcm_poll_descriptors_revents, since there are events that do
not necessarily correspond to POLLIN or POLLOUT (such as period
events), but I believe this is a lot less obvious and needs
confirmation first.

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