diff --git a/clutter/x11/clutter-backend-x11.c b/clutter/x11/clutter-backend-x11.c
index 8a78c1937..448af6481 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 08cf1aa0b..f02be504b 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)