client: update documentation about threading

Remove out-dated documentation and add few more words
about this topic.

v2. replace a paragraph by better explanation from Pekka Paalanen
    fix other notes from reviewing

v3. fix typo

v4. fix flags for poll in an example

    add wl_display_cancel_read() to another example
    (so that user sees that it should be used)

    move proper use of wl_display_prepare_read
    before the explanation why it is wrong to use
    wl_display_displach

Signed-off-by: Marek Chalupa <mchqwerty@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Daniel Stone <daniel@fooishbar.org>