doc: Improve libwayland-client doxygen documentation

Document wl_proxy, wl_display and wl_event_queue classes and add a
description to all public entry points. Also fix some typos.

src/wayland-client.h

@@ -31,15 +31,63 @@ extern "C" {
 #endif
 
 /** \class wl_proxy
+ *
+ * \brief Represents a protocol object on the client side.
+ *
+ * A wl_proxy acts as a client side proxy to an object existing in the
+ * compositor. The proxy is responsible for converting requests made by the
+ * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
+ * coming from the compositor are also handled by the proxy, which will in
+ * turn call the handler set with \ref wl_proxy_add_listener().
+ *
+ * \note With the exception of function \ref wl_proxy_set_queue(), functions
+ * accessing a \ref wl_proxy are not normally used by client code. Clients
+ * should normally use the higher level interface generated by the scanner to
+ * interact with compositor objects.
  *
  */
 struct wl_proxy;
 
 /** \class wl_display
+ *
+ * \brief Represents a connection to the compositor and acts as a proxy to
+ * the wl_display singleton object.
+ *
+ * A \ref wl_display object represents a client connection to a Wayland
+ * compositor. It is created with either \ref wl_display_connect() or
+ * \ref wl_display_connect_to_fd(). A connection is terminated using
+ * \ref wl_display_disconnect().
+ *
+ * A \ref wl_display is also used as the \ref wl_proxy for the \ref wl_display
+ * singleton object on the compositor side.
+ *
+ * A \ref wl_display object handles all the data sent from and to the
+ * compositor. When a \ref wl_proxy marshals a request, it will write its wire
+ * representation to the display's write buffer. The data is sent to the
+ * compositor when the client calls \ref wl_display_flush().
+ *
+ * Event handling is done in a thread-safe manner using event queues. The
+ * display has a \em main event queue where initially all the events are
+ * queued. The listeners for the events queued in it are called when the
+ * client calls \ref wl_display_dispatch().
+ *
+ * The client can create additional event queues with \ref
+ * wl_display_create_queue() and assign different \ref wl_proxy objects to it.
+ * The events for a proxy are always queued only on its assign queue, that can
+ * be dispatched by a different thread with \ref wl_display_dispatch_queue().
+ *
+ * All the \ref wl_display's functions are thread-safe.
+ *
  */
 struct wl_display;
 
 /** \class wl_event_queue
+ *
+ * \brief A queue for \ref wl_proxy object events.
+ *
+ * Event queues allows the events on a display to be handled in a thread-safe
+ * manner. See \ref wl_display for details.
+ *
  */
 struct wl_event_queue;