Commit 3f94d984 authored by Ander Conselvan de Oliveira's avatar Ander Conselvan de Oliveira Committed by Kristian Høgsberg

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.
parent 2320757e
......@@ -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
* proxy are received, user_data will be supplied to its listener.
* Set the user data associated with \c proxy. When events for this
* 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()
......
......@@ -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;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment