2006-10-21 Havoc Pennington <hp@redhat.com>

	* Document a bunch of undocumented stuff

1 files changed, 11 insertions, 7 deletions

diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 81c7cadf..9cd645b8 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -4578,13 +4578,13 @@ dbus_connection_set_timeout_functions   (DBusConnection            *connection,
 }
 
 /**
- * Sets the mainloop wakeup function for the connection. This function is
- * responsible for waking up the main loop (if its sleeping) when some some
- * change has happened to the connection that the mainloop needs to reconsider
- * (e.g. a message has been queued for writing).
- * When using Qt, this typically results in a call to QEventLoop::wakeUp().
- * When using GLib, it would call g_main_context_wakeup().
- *
+ * Sets the mainloop wakeup function for the connection. This function
+ * is responsible for waking up the main loop (if its sleeping in
+ * another thread) when some some change has happened to the
+ * connection that the mainloop needs to reconsider (e.g. a message
+ * has been queued for writing).  When using Qt, this typically
+ * results in a call to QEventLoop::wakeUp().  When using GLib, it
+ * would call g_main_context_wakeup().
  *
  * @param connection the connection.
  * @param wakeup_main_function function to wake up the mainloop
@@ -4628,6 +4628,10 @@ dbus_connection_set_wakeup_main_function (DBusConnection            *connection,
  * that messages should be dispatched later, when the main loop
  * is re-entered.
  *
+ * If you don't set a dispatch status function, you have to be sure to
+ * dispatch on every iteration of your main loop, especially if
+ * dbus_watch_handle() or dbus_timeout_handle() were called.
+ *
  * @param connection the connection
  * @param function function to call on dispatch status changes
  * @param data data for function