[PATCH vignatti/wayland/doc 2/2] doc: Add some doxygen documentation to wayland-client entry points
Tiago Vignatti
tiago.vignatti at linux.intel.com
Fri Oct 12 09:00:27 PDT 2012
cool, thanks! I applied both on my tree and, if you don't mind, I
inserted your signed-off-by there.
Tiago
On 10/12/2012 05:28 PM, Ander Conselvan de Oliveira wrote:
> Add some brief documentation for the public libwayland-client entry
> points. This is by no means complete, some funcions are still
> undocumented and some might need extra information.
> ---
> doc/doxygen/wayland.doxygen.in | 3 +-
> src/wayland-client.c | 169 ++++++++++++++++++++++++++++++++++++++++
> src/wayland-client.h | 17 ++--
> 3 files changed, 180 insertions(+), 9 deletions(-)
>
> diff --git a/doc/doxygen/wayland.doxygen.in b/doc/doxygen/wayland.doxygen.in
> index 323f5b4..c47a5ec 100644
> --- a/doc/doxygen/wayland.doxygen.in
> +++ b/doc/doxygen/wayland.doxygen.in
> @@ -648,7 +648,8 @@ WARN_LOGFILE =
> # directories like "/usr/src/myproject". Separate the files or directories
> # with spaces.
>
> -INPUT = @top_srcdir@/src/wayland-client.h
> +INPUT = @top_srcdir@/src/wayland-client.c \
> + @top_srcdir@/src/wayland-client.h
>
> # This tag can be used to specify the character encoding of the source files
> # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
> diff --git a/src/wayland-client.c b/src/wayland-client.c
> index 8ced6cc..ee3b0c4 100644
> --- a/src/wayland-client.c
> +++ b/src/wayland-client.c
> @@ -42,6 +42,9 @@
> #include "wayland-client.h"
> #include "wayland-private.h"
>
> +
> +/** \cond */
> +
> struct wl_proxy {
> struct wl_object object;
> struct wl_display *display;
> @@ -73,6 +76,8 @@ struct wl_display {
> pthread_mutex_t mutex;
> };
>
> +/** \endcond */
> +
> static int wl_debug = 0;
>
> static void
> @@ -96,6 +101,15 @@ wl_event_queue_release(struct wl_event_queue *queue)
> pthread_cond_destroy(&queue->cond);
> }
>
> +/** Destroy an event queue
> + *
> + * \param queue The event queue to be destroyed
> + *
> + * Destroy the given event queue. Any pending event on that queue is
> + * discarded.
> + *
> + * \memberof wl_event_queue
> + */
> WL_EXPORT void
> wl_event_queue_destroy(struct wl_event_queue *queue)
> {
> @@ -103,6 +117,14 @@ wl_event_queue_destroy(struct wl_event_queue *queue)
> free(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
> + * failure.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT struct wl_event_queue *
> wl_display_create_queue(struct wl_display *display)
> {
> @@ -117,6 +139,10 @@ wl_display_create_queue(struct wl_display *display)
> return queue;
> }
>
> +/**
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT struct wl_proxy *
> wl_proxy_create(struct wl_proxy *factory, const struct wl_interface *interface)
> {
> @@ -165,6 +191,12 @@ wl_proxy_create_for_id(struct wl_proxy *factory,
> return proxy;
> }
>
> +/** Destroy a proxy object
> + *
> + * \param proxy The proxy to be destroyed
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT void
> wl_proxy_destroy(struct wl_proxy *proxy)
> {
> @@ -184,6 +216,23 @@ wl_proxy_destroy(struct wl_proxy *proxy)
> free(proxy);
> }
>
> +/** Set a proxy's listener
> + *
> + * \param proxy The proxy object
> + * \param implementation The listener to be added to proxy
> + * \param data User data to be associated with the proxy
> + * \return 0 on success or -1 on failure
> + *
> + * Set proxy's listener to \c implementation and its user data to
> + * \c data. Ifa listener has already been set, this functions
> + * fails and nothing is changed.
> + *
> + * \c implementation is a vector of function pointers. For an opcode
> + * \c n, \c implemention[n] should point to the handler of \c n for
> + * the given object.
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT int
> wl_proxy_add_listener(struct wl_proxy *proxy,
> void (**implementation)(void), void *data)
> @@ -199,6 +248,10 @@ wl_proxy_add_listener(struct wl_proxy *proxy,
> return 0;
> }
>
> +/**
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT void
> wl_proxy_marshal(struct wl_proxy *proxy, uint32_t opcode, ...)
> {
> @@ -317,6 +370,13 @@ connect_to_socket(const char *name)
> return fd;
> }
>
> +/** Connect to Wayland display on an already open fd
> + *
> + * \param fd The fd to use for the connection
> + * \return A \ref wl_display object or \c NULL on failure
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT struct wl_display *
> wl_display_connect_to_fd(int fd)
> {
> @@ -360,6 +420,17 @@ wl_display_connect_to_fd(int fd)
> return display;
> }
>
> +/** Connect to a Wayland display
> + *
> + * \param name Name of the Wayland display to connect to
> + * \return A \ref wl_display object or \c NULL on failure
> + *
> + * Connect to the Wayland display named \c name. If \c name is \c NULL,
> + * its value will bee replaced with the WAYLAND_DISPLAY environment
> + * variable if it is set, otherwise display "wayland-0" will be used.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT struct wl_display *
> wl_display_connect(const char *name)
> {
> @@ -390,6 +461,15 @@ wl_display_connect(const char *name)
> return display;
> }
>
> +/** Close a connection to a Wayland display
> + *
> + * \param display The display context object
> + *
> + * Close the connection to \c display and free all resources associated
> + * with it.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT void
> wl_display_disconnect(struct wl_display *display)
> {
> @@ -404,6 +484,16 @@ wl_display_disconnect(struct wl_display *display)
> free(display);
> }
>
> +/** Get a display context's file descriptor
> + *
> + * \param display The display context object
> + * \return Display object file descriptor
> + *
> + * Return the file descriptor associated with a display so it can be
> + * integrated into the client's main loop.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT int
> wl_display_get_fd(struct wl_display *display)
> {
> @@ -423,6 +513,15 @@ static const struct wl_callback_listener sync_listener = {
> sync_callback
> };
>
> +/** Block until all pending request are processed by the server
> + *
> + * \param display The display context object
> + *
> + * Blocks until the server process all currently issued requests and
> + * sends out pending events on all event queues.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT void
> wl_display_roundtrip(struct wl_display *display)
> {
> @@ -552,6 +651,17 @@ dispatch_event(struct wl_display *display, struct wl_event_queue *queue)
> }
>
>
> +/** Dispatch events in an event queue
> + *
> + * \param display The display context object
> + * \param queue The event queue to dispatch
> + * \return 0 on success; -1 on failure
> + *
> + * Dispatch all incoming events for objects assigned to the given
> + * event queue. On failure -1 is returned and errno set appropriately.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT int
> wl_display_dispatch_queue(struct wl_display *display,
> struct wl_event_queue *queue)
> @@ -588,6 +698,17 @@ wl_display_dispatch_queue(struct wl_display *display,
> return 0;
> }
>
> +/** Dispatch a display's main event queue
> + *
> + * \param display The display context object
> + * \return 0 on success or -1 on failure
> + *
> + * Dispatch the display's main event queue.
> + *
> + * \sa wl_display_dispatch_queue()
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT int
> wl_display_dispatch(struct wl_display *display)
> {
> @@ -596,6 +717,18 @@ wl_display_dispatch(struct wl_display *display)
> return wl_display_dispatch_queue(display, &display->queue);
> }
>
> +/** Send all buffered request on the display to the server
> + *
> + * \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
> + * 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.
> + *
> + * \memberof wl_display
> + */
> WL_EXPORT int
> wl_display_flush(struct wl_display *display)
> {
> @@ -610,18 +743,42 @@ wl_display_flush(struct wl_display *display)
> return ret;
> }
>
> +/** Set the user data associated with a proxy
> + *
> + * \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.
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT void
> wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data)
> {
> proxy->user_data = user_data;
> }
>
> +/** Get the user data associated with a proxy
> + *
> + * \param proxy The proxy object
> + * \return The user data associated with proxy
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT void *
> wl_proxy_get_user_data(struct wl_proxy *proxy)
> {
> return proxy->user_data;
> }
>
> +/** Get the id of a proxy object
> + *
> + * \param proxy The proxy object
> + * \return The id the object associated with the proxy
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT uint32_t
> wl_proxy_get_id(struct wl_proxy *proxy)
> {
> @@ -629,6 +786,18 @@ wl_proxy_get_id(struct wl_proxy *proxy)
> }
>
>
> +/** Assign a proxy to an event queue
> + *
> + * \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
> + * queued in \c queue instead of the display's main queue.
> + *
> + * \sa wl_display_dispatch_queue()
> + *
> + * \memberof wl_proxy
> + */
> WL_EXPORT void
> wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue)
> {
> diff --git a/src/wayland-client.h b/src/wayland-client.h
> index 088407a..d47ffae 100644
> --- a/src/wayland-client.h
> +++ b/src/wayland-client.h
> @@ -30,8 +30,17 @@
> extern "C" {
> #endif
>
> +/** \class wl_proxy
> + *
> + */
> struct wl_proxy;
> +
> +/** \class wl_display
> + */
> struct wl_display;
> +
> +/** \class wl_event_queue
> + */
> struct wl_event_queue;
>
> void wl_event_queue_destroy(struct wl_event_queue *queue);
> @@ -56,14 +65,6 @@ typedef void (*wl_callback_func_t)(void *data, uint32_t time);
> struct wl_display *wl_display_connect(const char *name);
> struct wl_display *wl_display_connect_to_fd(int fd);
> void wl_display_disconnect(struct wl_display *display);
> -
> -/**
> - * @brief Connect to a Wayland socket
> - * @param display: The display context object
> - * @return Display object file descriptor
> - *
> - * \b this is the detailed description
> - */
> int wl_display_get_fd(struct wl_display *display);
> int wl_display_dispatch(struct wl_display *display);
> int wl_display_dispatch_queue(struct wl_display *display,
>
More information about the wayland-devel
mailing list