From 99d7d31318b44eacf8d8a64ee1bb92fc511ab8ce Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Thu, 22 Jul 2010 10:48:21 +0100
Subject: [PATCH] docs: Improve the text of X11 event-related functions

We need to make sure that people disabling event handling in Clutter
call clutter_x11_handle_event() to update Clutter's internal state.
---
 clutter/x11/clutter-backend-x11.c | 15 ++++++++++-----
 clutter/x11/clutter-event-x11.c   |  8 ++++++--
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/clutter/x11/clutter-backend-x11.c b/clutter/x11/clutter-backend-x11.c
index 8a78c19..448af64 100644
--- a/clutter/x11/clutter-backend-x11.c
+++ b/clutter/x11/clutter-backend-x11.c
@@ -673,12 +673,17 @@ clutter_x11_enable_xinput (void)
 }
 
 /**
- * clutter_x11_disable_event_retrieval
+ * clutter_x11_disable_event_retrieval:
  *
- * Disables retrieval of X events in the main loop. Use to create event-less
- * canvas or in conjunction with clutter_x11_handle_event.
+ * Disables the internal handling of X11 events in the main loop.
  *
- * This function can only be called before calling clutter_init().
+ * Libraries or applications calling this function will be responsible of
+ * handling all X11 events.
+ *
+ * You also must call clutter_x11_handle_event() to let Clutter process
+ * events and maintain its internal state.
+ *
+ * <note>This function can only be called before calling clutter_init().</note>
  *
  * Since: 0.8
  */
@@ -696,7 +701,7 @@ clutter_x11_disable_event_retrieval (void)
 }
 
 /**
- * clutter_x11_has_event_retrieval
+ * clutter_x11_has_event_retrieval:
  *
  * Queries the X11 backend to check if event collection has been disabled.
  *
diff --git a/clutter/x11/clutter-event-x11.c b/clutter/x11/clutter-event-x11.c
index 08cf1aa..f02be50 100644
--- a/clutter/x11/clutter-event-x11.c
+++ b/clutter/x11/clutter-event-x11.c
@@ -1099,7 +1099,11 @@ events_queue (ClutterBackend *backend)
  * @xevent: pointer to XEvent structure
  *
  * This function processes a single X event; it can be used to hook
- * into external X event retrieval (for example that done by GDK).
+ * into external X11 event processing (for example, a GDK filter
+ * function).
+ *
+ * If clutter_x11_disable_event_retrieval() has been called, you must
+ * let this function process events to update Clutter's internal state.
  *
  * Return value: #ClutterX11FilterReturn. %CLUTTER_X11_FILTER_REMOVE
  *  indicates that Clutter has internally handled the event and the
@@ -1109,7 +1113,7 @@ events_queue (ClutterBackend *backend)
  *  any exclusive action. %CLUTTER_X11_FILTER_TRANSLATE will not
  *  occur.
  *
- * Since:  0.8
+ * Since: 0.8
  */
 ClutterX11FilterReturn
 clutter_x11_handle_event (XEvent *xevent)
-- 
2.7.4