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

	* Document a bunch of undocumented stuff

9 files changed, 111 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index dc84b989..5766ecf9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2006-10-21  Havoc Pennington  <hp@redhat.com>
 
+	* Document a bunch of undocumented stuff
+	
+2006-10-21  Havoc Pennington  <hp@redhat.com>
+
 	* Clean up Doxygen group markers for public API so Doxygen finds
 	everything (not comprehensively fixed for private API).
 	Means all remaining Doxygen warnings are just about missing docs
diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c
index d92209d9..bb2a5899 100644
--- a/dbus/dbus-address.c
+++ b/dbus/dbus-address.c
@@ -214,7 +214,9 @@ create_entry (void)
 }
 
 /**
- * Returns the method string of an address entry.
+ * Returns the method string of an address entry.  For example, given
+ * the address entry "tcp:host=example.com" it would return the string
+ * "tcp"
  *
  * @param entry the entry.
  * @returns a string describing the method. This string
@@ -227,8 +229,12 @@ dbus_address_entry_get_method (DBusAddressEntry *entry)
 }
 
 /**
- * Returns a value from a key of an entry.
+ * Returns a value from a key of an entry. For example,
+ * given the address "tcp:host=example.com,port=8073" if you asked
+ * for the key "host" you would get the value "example.com"
  *
+ * The returned value is already unescaped.
+ * 
  * @param entry the entry.
  * @param key the key.
  * @returns the key value. This string must not be freed.
@@ -342,6 +348,9 @@ append_unescaped_value (DBusString       *unescaped,
  * method:key=value,key=value;method:key=value
  *
  * See the D-Bus specification for complete docs on the format.
+ *
+ * When connecting to an address, the first address entries
+ * in the semicolon-separated list should be tried first.
  * 
  * @param address the address.
  * @param entry return location to an array of entries.
@@ -589,7 +598,8 @@ dbus_address_escape_value (const char *value)
 
 /**
  * Unescapes the given string as a value in a key=value pair
- * for a D-Bus address.
+ * for a D-Bus address. Note that dbus_address_entry_get_value()
+ * returns an already-unescaped value.
  *
  * @param value the escaped value
  * @param error error to set if the unescaping fails
diff --git a/dbus/dbus-address.h b/dbus/dbus-address.h
index 8940be5b..8480e56a 100644
--- a/dbus/dbus-address.h
+++ b/dbus/dbus-address.h
@@ -37,6 +37,7 @@ DBUS_BEGIN_DECLS
  * @{
  */
 
+/** Opaque type representing one of the semicolon-separated items in an address */
 typedef struct DBusAddressEntry DBusAddressEntry;
 
 dbus_bool_t dbus_parse_address            (const char         *address,
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
diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h
index 465cdbf4..401154c1 100644
--- a/dbus/dbus-connection.h
+++ b/dbus/dbus-connection.h
@@ -39,13 +39,22 @@ DBUS_BEGIN_DECLS
  * @{
  */
 
+/* documented in dbus-watch.c */
 typedef struct DBusWatch DBusWatch;
+/* documented in dbus-timeout.c */
 typedef struct DBusTimeout DBusTimeout;
+/** Opaque type representing preallocated resources so a message can be sent without further memory allocation. */
 typedef struct DBusPreallocatedSend DBusPreallocatedSend;
+/** Opaque type representing a method call that has not yet received a reply. */
 typedef struct DBusPendingCall DBusPendingCall;
+/** Opaque type representing a connection to a remote application and associated incoming/outgoing message queues. */
 typedef struct DBusConnection DBusConnection;
+/** Set of functions that must be implemented to handle messages sent to a particular object path. */
 typedef struct DBusObjectPathVTable DBusObjectPathVTable;
 
+/**
+ * Indicates the status of a #DBusWatch.
+ */
 typedef enum
 {
   DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
@@ -54,9 +63,14 @@ typedef enum
                                  *   the flag can be 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). */
+                                 *   can be present in current state).
+                                 */
 } DBusWatchFlags;
 
+/**
+ * Indicates the status of incoming data on a #DBusConnection. This determines whether
+ * dbus_connection_dispatch() needs to be called.
+ */
 typedef enum
 {
   DBUS_DISPATCH_DATA_REMAINS,  /**< There is more data to potentially convert to messages. */
@@ -64,30 +78,75 @@ typedef enum
   DBUS_DISPATCH_NEED_MEMORY    /**< More memory is needed to continue. */
 } DBusDispatchStatus;
 
+/** Called when libdbus needs a new watch to be monitored by the main
+ * loop. Returns #FALSE if it lacks enough memory to add the
+ * watch. Set by dbus_connection_set_watch_functions() or
+ * dbus_server_set_watch_functions().
+ */
 typedef dbus_bool_t (* DBusAddWatchFunction)       (DBusWatch      *watch,
                                                     void           *data);
+/** Called when dbus_watch_get_enabled() may return a different value
+ *  than it did before.  Set by dbus_connection_set_watch_functions()
+ *  or dbus_server_set_watch_functions().
+ */
 typedef void        (* DBusWatchToggledFunction)   (DBusWatch      *watch,
                                                     void           *data);
+/** Called when libdbus no longer needs a watch to be monitored by the
+ * main loop. Set by dbus_connection_set_watch_functions() or
+ * dbus_server_set_watch_functions().
+ */
 typedef void        (* DBusRemoveWatchFunction)    (DBusWatch      *watch,
                                                     void           *data);
+/** Called when libdbus needs a new timeout to be monitored by the main
+ * loop. Returns #FALSE if it lacks enough memory to add the
+ * watch. Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
 typedef dbus_bool_t (* DBusAddTimeoutFunction)     (DBusTimeout    *timeout,
                                                     void           *data);
+/** Called when dbus_timeout_get_enabled() may return a different
+ * value than it did before.
+ * Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
 typedef void        (* DBusTimeoutToggledFunction) (DBusTimeout    *timeout,
                                                     void           *data);
+/** Called when libdbus no longer needs a timeout to be monitored by the
+ * main loop. Set by dbus_connection_set_timeout_functions() or
+ * dbus_server_set_timeout_functions().
+ */
 typedef void        (* DBusRemoveTimeoutFunction)  (DBusTimeout    *timeout,
                                                     void           *data);
+/** Called when the return value of dbus_connection_get_dispatch_status()
+ * may have changed. Set with dbus_connection_set_dispatch_status_function().
+ */
 typedef void        (* DBusDispatchStatusFunction) (DBusConnection *connection,
                                                     DBusDispatchStatus new_status,
                                                     void           *data);
+/**
+ * Called when the main loop's thread should be notified that there's now work
+ * to do. Set with dbus_connection_set_wakeup_main_function().
+ */
 typedef void        (* DBusWakeupMainFunction)     (void           *data);
+/**
+ * Called during authentication on UNIX systems to check whether the given
+ * user ID is allowed to connect. Never called on Windows. Set with
+ * dbus_connection_set_unix_user_function().
+ */ 
 typedef dbus_bool_t (* DBusAllowUnixUserFunction)  (DBusConnection *connection,
                                                     unsigned long   uid,
                                                     void           *data);
-
+/**
+ * Called when a pending call now has a reply available. Set with
+ * dbus_pending_call_set_notify().
+ */
 typedef void (* DBusPendingCallNotifyFunction) (DBusPendingCall *pending,
                                                 void            *user_data);
 
-
+/**
+ * Called when a message needs to be handled. The result indicates whether or
+ * not more handlers should be run. Set with dbus_connection_add_filter().
+ */
 typedef DBusHandlerResult (* DBusHandleMessageFunction) (DBusConnection     *connection,
                                                          DBusMessage        *message,
                                                          void               *user_data);
@@ -220,15 +279,26 @@ void                  dbus_connection_send_preallocated      (DBusConnection
 
 /* Object tree functionality */
 
+/**
+ * Called when a #DBusObjectPathVTable is unregistered (or its connection is freed).
+ * Found in #DBusObjectPathVTable.
+ */
 typedef void              (* DBusObjectPathUnregisterFunction) (DBusConnection  *connection,
                                                                 void            *user_data);
+/**
+ * Called when a message is sent to a registered object path. Found in
+ * #DBusObjectPathVTable which is registered with dbus_connection_register_object_path()
+ * or dbus_connection_register_fallback().
+ */
 typedef DBusHandlerResult (* DBusObjectPathMessageFunction)    (DBusConnection  *connection,
                                                                 DBusMessage     *message,
                                                                 void            *user_data);
 
 /**
  * Virtual table that must be implemented to handle a portion of the
- * object path hierarchy.
+ * object path hierarchy. Attach the vtable to a particular path using
+ * dbus_connection_register_object_path() or
+ * dbus_connection_register_fallback().
  */
 struct DBusObjectPathVTable
 {
diff --git a/dbus/dbus-errors.h b/dbus/dbus-errors.h
index 3ea12f0c..e4548604 100644
--- a/dbus/dbus-errors.h
+++ b/dbus/dbus-errors.h
@@ -38,6 +38,7 @@ DBUS_BEGIN_DECLS
  * @{
  */
 
+/** Mostly-opaque type representing an error that occurred */
 typedef struct DBusError DBusError;
 
 /**
@@ -45,8 +46,8 @@ typedef struct DBusError DBusError;
  */
 struct DBusError
 {
-  const char *name;    /**< error name */
-  const char *message; /**< error message */
+  const char *name;    /**< public error name field */
+  const char *message; /**< public error message field */
 
   unsigned int dummy1 : 1; /**< placeholder */
   unsigned int dummy2 : 1; /**< placeholder */
diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h
index 3436b6ce..e5f0bdae 100644
--- a/dbus/dbus-marshal-validate.h
+++ b/dbus/dbus-marshal-validate.h
@@ -161,7 +161,7 @@ dbus_bool_t _dbus_validate_signature  (const DBusString *str,
 #else /* !DBUS_DISABLE_CHECKS */
 
 /** A name check is used in _dbus_return_if_fail(), it's not suitable
- * for validating untrusted data. use _dbus_validate_##what for that.
+ * for validating untrusted data. use _dbus_validate_whatever for that.
  */
 #define DECLARE_DBUS_NAME_CHECK(what) \
 dbus_bool_t _dbus_check_is_valid_##what (const char *name)
diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h
index 16d2272a..8fe07d8d 100644
--- a/dbus/dbus-message.h
+++ b/dbus/dbus-message.h
@@ -42,6 +42,7 @@ DBUS_BEGIN_DECLS
  */
 
 typedef struct DBusMessage DBusMessage;
+/** Opaque type representing a message iterator. Can be copied by value, and contains no allocated memory so never needs to be freed and can be allocated on the stack. */
 typedef struct DBusMessageIter DBusMessageIter;
 
 /**
diff --git a/dbus/dbus-server.h b/dbus/dbus-server.h
index caea4d70..58e00289 100644
--- a/dbus/dbus-server.h
+++ b/dbus/dbus-server.h
@@ -41,6 +41,9 @@ DBUS_BEGIN_DECLS
 
 typedef struct DBusServer DBusServer;
 
+/** Called when a new connection to the server is available. Must reference and save the new
+ * connection, or close the new connection. Set with dbus_server_set_new_connection_function().
+ */
 typedef void (* DBusNewConnectionFunction) (DBusServer     *server,
                                             DBusConnection *new_connection,
                                             void           *data);