client: update obsolete comments

1) there is nothing like main thread since
   3c7e8bfb anymore, so remove
   it from documentation and update the doc accordingly.

2) use calling 'default queue' instead of 'main queue'. In the code
   we use display->default_queue, so it'll be easier the understand.

3) update some obsolete or unprecise pieces of documentation

v2. Not only remove out-of-date comment, but fix/remove more
    things across the wayland-client.[ch]

v3. fixes (rephrasing unclear paragraphs etc.)
    according to Pakka Paalanen notes (thanks)

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