diff --git a/src/wayland-client.c b/src/wayland-client.c
index cd94fd8..33eb247 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -1617,28 +1617,6 @@ wl_display_dispatch(struct wl_display *display)
  * attempt to read the display fd and simply returns zero if the main
  * queue is empty, i.e., it doesn't block.
  *
- * This is necessary when a client's main loop wakes up on some fd other
- * than the display fd (network socket, timer fd, etc) and calls \ref
- * wl_display_dispatch_queue() from that callback. This may queue up
- * events in other queues while reading all data from the display fd.
- * When the main loop returns from the handler, the display fd
- * no longer has data, causing a call to \em poll(2) (or similar
- * functions) to block indefinitely, even though there are events ready
- * to dispatch.
- *
- * To proper integrate the wayland display fd into a main loop, the
- * client should always call wl_display_dispatch_pending() and then
- * \ref wl_display_flush() prior to going back to sleep. At that point,
- * the fd typically doesn't have data so attempting I/O could block, but
- * events queued up on the default queue should be dispatched.
- *
- * A real-world example is a main loop that wakes up on a timerfd (or a
- * sound card fd becoming writable, for example in a video player), which
- * then triggers GL rendering and eventually eglSwapBuffers().
- * eglSwapBuffers() may call wl_display_dispatch_queue() if it didn't
- * receive the frame event for the previous frame, and as such queue
- * events in the default queue.
- *
  * \sa wl_display_dispatch(), wl_display_dispatch_queue(),
  * wl_display_flush()
  *