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.c

@@ -120,7 +120,7 @@ wl_event_queue_destroy(struct wl_event_queue *queue)
 /** Create a new event queue for this display
  *
  * \param display The display context object
- * \return A new event queue associated with this display on NULL on
+ * \return A new event queue associated with this display or NULL on
  * failure.
  *
  * \memberof wl_display
@@ -139,7 +139,22 @@ wl_display_create_queue(struct wl_display *display)
 	return queue;
 }
 
-/**
+/** Create a proxy object with a given interface
+ *
+ * \param factory Factory proxy object
+ * \param interface Interface the proxy object should use
+ * \return A newly allocated proxy object or NULL on failure
+ *
+ * This function creates a new proxy object with the supplied interface. The
+ * proxy object will have an id assigned from the client id space. The id
+ * should be created on the compositor side by sending an appropriate request
+ * with \ref wl_proxy_marshal().
+ *
+ * The proxy will inherit the display and event queue of the factory object.
+ *
+ * \note This should not normally be used by non-generated code.
+ *
+ * \sa wl_display, wl_event_queue, wl_proxy_marshal()
  *
  * \memberof wl_proxy
  */
@@ -248,7 +263,31 @@ wl_proxy_add_listener(struct wl_proxy *proxy,
 	return 0;
 }
 
-/**
+/** Prepare a request to be sent to the compositor
+ *
+ * \param proxy The proxy object
+ * \param opcode Opcode of the request to be sent
+ * \param ... Extra arguments for the given request
+ *
+ * Translates the request given by opcode and the extra arguments into the
+ * wire format and write it to the connection buffer.
+ *
+ * The example below creates a proxy object with the wl_surface_interface
+ * using a wl_compositor factory interface and sends the
+ * \c compositor.create_surface request using \ref wl_proxy_marshal(). Note
+ * the \c id is the extra argument to the request as specified by the
+ * protocol.
+ *
+ * \code
+ * id = wl_proxy_create((struct wl_proxy *) wl_compositor,
+ *                      &wl_surface_interface);
+ * wl_proxy_marshal((struct wl_proxy *) wl_compositor,
+ *                  WL_COMPOSITOR_CREATE_SURFACE, id);
+ * \endcode
+ *
+ * \note This should not normally be used by non-generated code.
+ *
+ * \sa wl_proxy_create()
  *
  * \memberof wl_proxy
  */
@@ -736,7 +775,7 @@ wl_display_dispatch_pending(struct wl_display *display)
  * \param display The display context object
  * \return The number of bytes send on success or -1 on failure
  *
- * Send all buffered data on the client side to the servre. Clients
+ * Send all buffered data on the client side to the server. Clients
  * should call this function before blocking. On success, the number
  * of bytes sent to the server is returned. On failure, this
  * function returns -1 and errno is set appropriately.
@@ -762,8 +801,8 @@ wl_display_flush(struct wl_display *display)
  * \param proxy The proxy object
  * \param user_data The data to be associated with proxy
  *
- * Set the user data associated with proxy. When events for this
+ * Set the user data associated with \c proxy. When events for this
- * proxy are received, user_data will be supplied to its listener.
+ * proxy are received, \c user_data will be supplied to its listener.
  *
  * \memberof wl_proxy
  */
@@ -805,7 +844,7 @@ wl_proxy_get_id(struct wl_proxy *proxy)
  * \param proxy The proxy object
  * \param queue The event queue that will handle this proxy
  *
- * Assign proxy to event queue. Events coming from proxy will be
+ * Assign proxy to event queue. Events coming from \c proxy will be
  * queued in \c queue instead of the display's main queue.
  *
  * \sa wl_display_dispatch_queue()

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;