Documentation of known misuse of PulseAudio API

Hello.

Over time, I became aware of several instances of tempting but
semantically incorrect usage of PulseAudio API (one from my own bad
proposal of "improving" Wine, one from Parole media player and one
from Webkit-GTK). I want to document these gotchas so that other
developers don't fall for that. See the attached patch.

I have checked that the rendered HTML is correct, but need someone to
confirm the factual accuracy of the proposed changes and, possibly, to
improve the wording.

--
Alexander E. Patrakov
bluez5-util: Free the adapter_path in device_free().
alsa-mixer: Free the description key in alsa_path_free().
caps: Remove the FreeBSD implementation of pa_drop_caps()

Quoting Ryan Lortie from [1]:

I assumed from my reading of the Linux code ("cap_clear()...") that it
was clearing all capabilities of the process when in fact it is only
clearing the "special to root" capabilities.

The FreeBSD version of the code indeed clears _all_ capabilities beyond
ones that the process already has (ie: cannot open any new files, create
sockets, etc.)

This has a pretty obvious adverse effect on pulseaudio's ability to do
what it needs to do -- indeed, it bombs out pretty quickly due to an
inability to read its own config file.

[1] https://bugs.freedesktop.org/show_bug.cgi?id=72580#c11
module-rtp-recv: Add an argument for latency
volume-test: Increase the allowed number of rouding errors

BugLink: https://bugs.freedesktop.org/show_bug.cgi?id=72374