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

	* More documentation - all public API now documented according to
	Doxygen

8 files changed, 119 insertions, 26 deletions

diff --git a/ChangeLog b/ChangeLog
index 5766ecf9..057972e0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2006-10-21  Havoc Pennington  <hp@redhat.com>
 
+	* More documentation - all public API now documented according to
+	Doxygen
+
+2006-10-21  Havoc Pennington  <hp@redhat.com>
+
 	* Document a bunch of undocumented stuff
 	
 2006-10-21  Havoc Pennington  <hp@redhat.com>
diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 9cd645b8..acba9ba9 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -533,7 +533,10 @@ _dbus_connection_has_messages_to_send_unlocked (DBusConnection *connection)
 
 /**
  * Checks whether there are messages in the outgoing message queue.
- *
+ * Use dbus_connection_flush() to block until all outgoing
+ * messages have been written to the underlying transport
+ * (such as a socket).
+ * 
  * @param connection the connection.
  * @returns #TRUE if the outgoing queue is non-empty.
  */
diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h
index 401154c1..7d775a2f 100644
--- a/dbus/dbus-connection.h
+++ b/dbus/dbus-connection.h
@@ -59,11 +59,15 @@ typedef enum
 {
   DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
   DBUS_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */
-  DBUS_WATCH_ERROR    = 1 << 2, /**< As in POLLERR (can't watch for this, but
-                                 *   the flag can be passed to dbus_watch_handle()).
+  DBUS_WATCH_ERROR    = 1 << 2, /**< As in POLLERR (can't watch for
+                                 *   this, but can be present in
+                                 *   current state passed to
+                                 *   dbus_watch_handle()).
                                  */
-  DBUS_WATCH_HANGUP   = 1 << 3  /**< As in POLLHUP (can't watch for it, but
-                                 *   can be present in current state).
+  DBUS_WATCH_HANGUP   = 1 << 3  /**< As in POLLHUP (can't watch for
+                                 *   it, but can be present in current
+                                 *   state passed to
+                                 *   dbus_watch_handle()).
                                  */
 } DBusWatchFlags;
 
diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h
index a36e67c3..6198fd88 100644
--- a/dbus/dbus-protocol.h
+++ b/dbus/dbus-protocol.h
@@ -41,9 +41,10 @@ extern "C" {
  * @defgroup DBusProtocol Protocol constants
  * @ingroup  DBus
  *
- * D-Bus protocol constants
+ * @brief Defines constants which are part of the D-Bus protocol
+ *
+ * This header is intended for use by any library, not only libdbus.
  *
- * @brief  Defines constants which are part of the D-Bus protocol
  * @{
  */
 
@@ -349,7 +350,11 @@ extern "C" {
 #define DBUS_ERROR_AUTH_FAILED                "org.freedesktop.DBus.Error.AuthFailed"
 /** Unable to connect to server (probably caused by ECONNREFUSED on a socket). */
 #define DBUS_ERROR_NO_SERVER                  "org.freedesktop.DBus.Error.NoServer"
-/** Certain timeout errors, possibly ETIMEDOUT on a socket. Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts. */
+/** Certain timeout errors, possibly ETIMEDOUT on a socket.
+ * Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts.
+ * @warning this is confusingly-named given that #DBUS_ERROR_TIMED_OUT also exists. We can't fix
+ * it for compatibility reasons so just be careful.
+ */
 #define DBUS_ERROR_TIMEOUT                    "org.freedesktop.DBus.Error.Timeout"
 /** No network access (probably ENETUNREACH on a socket). */
 #define DBUS_ERROR_NO_NETWORK                 "org.freedesktop.DBus.Error.NoNetwork"
@@ -365,7 +370,10 @@ extern "C" {
 #define DBUS_ERROR_FILE_EXISTS                "org.freedesktop.DBus.Error.FileExists"
 /** Method name you invoked isn't known by the object you invoked it on. */
 #define DBUS_ERROR_UNKNOWN_METHOD             "org.freedesktop.DBus.Error.UnknownMethod"
-/** Certain other timeout errors, e.g. while starting a service. @todo redundant with #DBUS_ERROR_TIMEOUT */
+/** Certain timeout errors, e.g. while starting a service.
+ * @warning this is confusingly-named given that #DBUS_ERROR_TIMEOUT also exists. We can't fix
+ * it for compatibility reasons so just be careful.
+ */
 #define DBUS_ERROR_TIMED_OUT                  "org.freedesktop.DBus.Error.TimedOut"
 /** Tried to remove or modify a match rule that didn't exist. */
 #define DBUS_ERROR_MATCH_RULE_NOT_FOUND       "org.freedesktop.DBus.Error.MatchRuleNotFound"
diff --git a/dbus/dbus-shared.h b/dbus/dbus-shared.h
index 78d305ef..6d9284e7 100644
--- a/dbus/dbus-shared.h
+++ b/dbus/dbus-shared.h
@@ -40,9 +40,12 @@ extern "C" {
  * @defgroup DBusShared Shared constants 
  * @ingroup  DBus
  *
- * Shared constants.
+ * @brief Shared header included by both libdbus and C/C++ bindings such as the GLib bindings.
+ *
+ * Usually a C/C++ binding such as the GLib or Qt binding won't want to include dbus.h in its
+ * public headers. However, a few constants and macros may be useful to include; those are
+ * found here and in dbus-protocol.h
  *
- * @brief Stuff used by both dbus/dbus.h low-level and C/C++ binding APIs 
  * @{
  */
 
diff --git a/dbus/dbus-threads.c b/dbus/dbus-threads.c
index 702cbda7..1fbf48b6 100644
--- a/dbus/dbus-threads.c
+++ b/dbus/dbus-threads.c
@@ -520,18 +520,44 @@ init_locks (void)
 
 /**
  * 
- * Initializes threads. If this function is not called,
- * the D-Bus library will not lock any data structures.
- * If it is called, D-Bus will do locking, at some cost
- * in efficiency. Note that this function must be called
- * BEFORE the second thread is started.
+ * Initializes threads. If this function is not called, the D-Bus
+ * library will not lock any data structures.  If it is called, D-Bus
+ * will do locking, at some cost in efficiency. Note that this
+ * function must be called BEFORE the second thread is started.
  *
- * Use dbus_threads_init_default() if you don't need a
- * particular thread implementation.
+ * Almost always, you should use dbus_threads_init_default() instead.
+ * The raw dbus_threads_init() is only useful if you require a
+ * particular thread implementation for some reason.
  *
- * This function may be called more than once.  The first
- * one wins.
+ * A possible reason to use dbus_threads_init() rather than
+ * dbus_threads_init_default() is to insert debugging checks or print
+ * statements.
  *
+ * dbus_threads_init() may be called more than once.  The first one
+ * wins and subsequent calls are ignored. (Unless you use
+ * dbus_shutdown() to reset libdbus, which will let you re-init
+ * threads.)
+ *
+ * Either recursive or nonrecursive mutex functions must be specified,
+ * but not both. New code should provide only the recursive functions
+ * - specifying the nonrecursive ones is deprecated.
+ *
+ * Because this function effectively sets global state, all code
+ * running in a given application must agree on the thread
+ * implementation. Most code won't care which thread implementation is
+ * used, so there's no problem. However, usually libraries should not
+ * call dbus_threads_init() or dbus_threads_init_default(), instead
+ * leaving this policy choice to applications.
+ *
+ * The exception is for application frameworks (GLib, Qt, etc.)  and
+ * D-Bus bindings based on application frameworks. These frameworks
+ * define a cross-platform thread abstraction and can assume
+ * applications using the framework are OK with using that thread
+ * abstraction.
+ *
+ * However, even these app frameworks may find it easier to simply call
+ * dbus_threads_init_default(), and there's no reason they shouldn't.
+ * 
  * @param functions functions for using threads
  * @returns #TRUE on success, #FALSE if no memory
  */
@@ -983,6 +1009,14 @@ static const DBusThreadFunctions internal_functions =
  * Calls dbus_threads_init() with a default set of
  * #DBusThreadFunctions appropriate for the platform.
  *
+ * Most applications should use this rather than dbus_threads_init().
+ *
+ * It's safe to call dbus_threads_init_default() as many times as you
+ * want, but only the first time will have an effect.
+ *
+ * dbus_shutdown() reverses the effects of this function when it
+ * resets all global state in libdbus.
+ * 
  * @returns #TRUE on success, #FALSE if not enough memory
  */
 dbus_bool_t
diff --git a/dbus/dbus-threads.h b/dbus/dbus-threads.h
index ff3a371b..344b0ffd 100644
--- a/dbus/dbus-threads.h
+++ b/dbus/dbus-threads.h
@@ -37,29 +37,61 @@ DBUS_BEGIN_DECLS
  * @{
  */
 
+/** An opaque mutex type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
 typedef struct DBusMutex DBusMutex;
+/** An opaque condition variable type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
 typedef struct DBusCondVar DBusCondVar;
 
+/** Deprecated, provide DBusRecursiveMutexNewFunction instead. */
 typedef DBusMutex*  (* DBusMutexNewFunction)    (void);
+/** Deprecated, provide DBusRecursiveMutexFreeFunction instead. */
 typedef void        (* DBusMutexFreeFunction)   (DBusMutex *mutex);
+/** Deprecated, provide DBusRecursiveMutexLockFunction instead. */
 typedef dbus_bool_t (* DBusMutexLockFunction)   (DBusMutex *mutex);
+/** Deprecated, provide DBusRecursiveMutexUnlockFunction instead. */
 typedef dbus_bool_t (* DBusMutexUnlockFunction) (DBusMutex *mutex);
 
+/** Creates a new recursively-lockable mutex, or returns #NULL if not enough memory.
+ * Found in #DBusThreadFunctions
+ */
 typedef DBusMutex*  (* DBusRecursiveMutexNewFunction)    (void);
+/** Frees a recursively-lockable mutex.  Found in #DBusThreadFunctions.
+ */
 typedef void        (* DBusRecursiveMutexFreeFunction)   (DBusMutex *mutex);
+/** Locks a recursively-lockable mutex.  Found in #DBusThreadFunctions.
+ */
 typedef void        (* DBusRecursiveMutexLockFunction)   (DBusMutex *mutex);
+/** Unlocks a recursively-lockable mutex.  Found in #DBusThreadFunctions.
+ */
 typedef void        (* DBusRecursiveMutexUnlockFunction) (DBusMutex *mutex);
 
+/** Creates a new condition variable.  Found in #DBusThreadFunctions.
+ */
 typedef DBusCondVar*  (* DBusCondVarNewFunction)         (void);
+/** Frees a condition variable.  Found in #DBusThreadFunctions.
+ */
 typedef void          (* DBusCondVarFreeFunction)        (DBusCondVar *cond);
+/** Waits on a condition variable.  Found in #DBusThreadFunctions.
+ */
 typedef void          (* DBusCondVarWaitFunction)        (DBusCondVar *cond,
 							  DBusMutex   *mutex);
+/** Waits on a condition variable with a timeout.  Found in #DBusThreadFunctions.
+ */
 typedef dbus_bool_t   (* DBusCondVarWaitTimeoutFunction) (DBusCondVar *cond,
 							  DBusMutex   *mutex,
 							  int          timeout_milliseconds);
+/** Wakes one waiting thread on a condition variable.  Found in #DBusThreadFunctions.
+ */
 typedef void          (* DBusCondVarWakeOneFunction) (DBusCondVar *cond);
+/** Wakes all waiting threads on a condition variable.  Found in #DBusThreadFunctions.
+ */
 typedef void          (* DBusCondVarWakeAllFunction) (DBusCondVar *cond);
 
+/**
+ * Flags indicating which functions are present in #DBusThreadFunctions. Used to allow
+ * the library to detect older callers of dbus_threads_init() if new possible functions
+ * are added to #DBusThreadFunctions.
+ */
 typedef enum 
 {
   DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK      = 1 << 0,
@@ -80,17 +112,18 @@ typedef enum
 } DBusThreadFunctionsMask;
 
 /**
- * Functions that must be implemented to make the D-Bus
- * library thread-aware. 
+ * Functions that must be implemented to make the D-Bus library
+ * thread-aware. The recursive mutex functions should be specified
+ * rather than the old, deprecated nonrecursive ones.
  */
 typedef struct
 {
   unsigned int mask; /**< Mask indicating which functions are present. */
 
-  DBusMutexNewFunction mutex_new; /**< Function to create a mutex */
-  DBusMutexFreeFunction mutex_free; /**< Function to free a mutex */
-  DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex */
-  DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex */
+  DBusMutexNewFunction mutex_new; /**< Function to create a mutex; optional and deprecated. */
+  DBusMutexFreeFunction mutex_free; /**< Function to free a mutex; optional and deprecated. */
+  DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex; optional and deprecated. */
+  DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex; optional and deprecated. */
 
   DBusCondVarNewFunction condvar_new; /**< Function to create a condition variable */
   DBusCondVarFreeFunction condvar_free; /**< Function to free a condition variable */
diff --git a/dbus/dbus-watch.c b/dbus/dbus-watch.c
index ebbb7ed2..f2691c82 100644
--- a/dbus/dbus-watch.c
+++ b/dbus/dbus-watch.c
@@ -483,6 +483,9 @@ _dbus_watch_set_handler (DBusWatch        *watch,
 /**
  * Gets the file descriptor that should be watched.
  *
+ * On Windows, this will be a socket. On UNIX right now it will be a
+ * socket but in principle it could be something else.
+ * 
  * @param watch the DBusWatch object.
  * @returns the file descriptor to watch.
  */