From: Bill Spitzak <spitzak@gmail.com>
Date: Sat, 3 Jan 2015 02:29:18 +0000 (-0800)
Subject: doc: made functions taking wl_event_queue arg belong to wl_event_queue
X-Git-Tag: 1.6.92~31
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1f39fbf8d282b3c70e8a78a37a0b2cf7ac863763;p=platform%2Fupstream%2Fwayland.git

doc: made functions taking wl_event_queue arg belong to wl_event_queue

The fact that these functions take both a display and queue argument is
I think historical, and they really are methods on the queue.

Also added some docs for wl_display_prepare_read_queue.

Reviewed-by: Derek Foreman <derekf@osg.samsung.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
---

diff --git a/src/wayland-client.c b/src/wayland-client.c
index d1d21ca..757d69c 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -260,7 +260,7 @@ wl_event_queue_destroy(struct wl_event_queue *queue)
  * \return A new event queue associated with this display or NULL on
  * failure.
  *
- * \memberof wl_display
+ * \memberof wl_event_queue
  */
 WL_EXPORT struct wl_event_queue *
 wl_display_create_queue(struct wl_display *display)
@@ -915,7 +915,7 @@ static const struct wl_callback_listener sync_listener = {
  * with calling wl_display_prepare_read() and wl_display_read_events())
  *
  * \sa wl_display_roundtrip()
- * \memberof wl_display
+ * \memberof wl_event_queue
  */
 WL_EXPORT int
 wl_display_roundtrip_queue(struct wl_display *display, struct wl_event_queue *queue)
@@ -1336,6 +1336,21 @@ err:
 	return -1;
 }
 
+/** Prepare to read events from the display to this queue
+ *
+ * \param display The display context object
+ * \param queue The event queue to use
+ * \return 0 on success or -1 if event queue was not empty
+ *
+ * Atomically makes sure the queue is empty and stops any other thread
+ * from placing events into this (or any) queue.  Caller must
+ * eventually call either wl_display_cancel_read() or
+ * wl_display_read_events(), usually after waiting for the
+ * display fd to become ready for reading, to release the lock.
+ *
+ * \sa wl_display_prepare_read
+ * \memberof wl_event_queue
+ */
 WL_EXPORT int
 wl_display_prepare_read_queue(struct wl_display *display,
 			      struct wl_event_queue *queue)
@@ -1497,7 +1512,7 @@ wl_display_cancel_read(struct wl_display *display)
  * \sa wl_display_dispatch(), wl_display_dispatch_pending(),
  * wl_display_dispatch_queue_pending()
  *
- * \memberof wl_display
+ * \memberof wl_event_queue
  */
 WL_EXPORT int
 wl_display_dispatch_queue(struct wl_display *display,
@@ -1569,7 +1584,7 @@ wl_display_dispatch_queue(struct wl_display *display,
  * event queue. On failure -1 is returned and errno set appropriately.
  * If there are no events queued, this function returns immediately.
  *
- * \memberof wl_display
+ * \memberof wl_event_queue
  * \since 1.0.2
  */
 WL_EXPORT int