- * The incoming message queue is filled when the connection
- * reads from its underlying transport (such as a socket).
- * Reading usually happens in dbus_watch_handle() or
- * dbus_connection_read_write().
- *
- * If any data has been read from the underlying transport, but not
- * yet dispatched, the dispatch status will be
- * #DBUS_DISPATCH_DATA_REMAINS. See dbus_connection_get_dispatch_status()
- * for more on dispatch statuses.
+ * If there are complete messages in the incoming queue,
+ * dbus_connection_dispatch() removes one message from the queue and
+ * processes it. Processing has three steps.
+ *
+ * First, any method replies are passed to #DBusPendingCall or
+ * dbus_connection_send_with_reply_and_block() in order to
+ * complete the pending method call.
+ *
+ * Second, any filters registered with dbus_connection_add_filter()
+ * are run. If any filter returns #DBUS_HANDLER_RESULT_HANDLED
+ * then processing stops after that filter.
+ *
+ * Third, if the message is a method call it is forwarded to
+ * any registered object path handlers added with
+ * dbus_connection_register_object_path() or
+ * dbus_connection_register_fallback().
+ *
+ * A single call to dbus_connection_dispatch() will process at most
+ * one message; it will not clear the entire message queue.