client: Correct documentation regarding thread safeness

The current documentation about wl_display_dispatch() states one may not
mix wl_display_dispatch(_queue)() with wl_display_prepare_read() and
friends, but this is a misconception about how
wl_display_dispatch(_queue)() works. The fact is that the dispatch
functions does the equivalent of what the preparation API does
internally, and it is safe to use together.

What is not safe is to dispatch using the wl_display_dispatch(_queue)()
functions while being prepared to read using wl_display_read_events().

This patch rewrites the documentation to correctly state when the
various API's are thread safe and how they may not be used.

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



Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Daniel Stone <daniels@collabora.com>