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

	* Fix a pile of Doxygen warnings and missing docs

31 files changed, 416 insertions, 73 deletions

diff --git a/ChangeLog b/ChangeLog
index 822cb860..452c84a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2006-10-19  Havoc Pennington  <hp@redhat.com>
+
+	* Fix a pile of Doxygen warnings and missing docs
+
 2006-10-19  John (J5) Palmieri  <johnp@redhat.com>
 
 	* bus/dir-watch-default.c, bus/dir-watch-dnotify.c, 
diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c
index c6354f14..d92209d9 100644
--- a/dbus/dbus-address.c
+++ b/dbus/dbus-address.c
@@ -49,8 +49,20 @@ struct DBusAddressEntry
 };
 
 
+/**
+ *
+ * Sets #DBUS_ERROR_BAD_ADDRESS.
+ * If address_problem_type and address_problem_field are not #NULL,
+ * sets an error message about how the field is no good. Otherwise, sets
+ * address_problem_other as the error message.
+ * 
+ * @param error the error to set
+ * @param address_problem_type the address type of the bad address or #NULL
+ * @param address_problem_field the missing field of the bad address or #NULL
+ * @param address_problem_other any other error message or #NULL
+ */
 void
-_dbus_set_bad_address (DBusError *error,
+_dbus_set_bad_address (DBusError  *error,
                        const char *address_problem_type,
                        const char *address_problem_field,
                        const char *address_problem_other)
@@ -65,6 +77,10 @@ _dbus_set_bad_address (DBusError *error,
                     address_problem_other);
 }
 
+/**
+ * #TRUE if the byte need not be escaped when found in a dbus address.
+ * All other bytes are required to be escaped in a valid address.
+ */
 #define _DBUS_ADDRESS_OPTIONALLY_ESCAPED_BYTE(b)        \
          (((b) >= 'a' && (b) <= 'z') ||                 \
           ((b) >= 'A' && (b) <= 'Z') ||                 \
@@ -615,6 +631,9 @@ dbus_address_unescape_value (const char *value,
 /** @} */ /* End of public API */
 
 #ifdef DBUS_BUILD_TESTS
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include "dbus-test.h"
 #include <stdlib.h>
 
@@ -782,4 +801,6 @@ _dbus_address_test (void)
   return TRUE;
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif
diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 4c1bce91..92fa15a8 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -373,18 +373,18 @@ _dbus_connection_queue_received_message (DBusConnection *connection,
  *        variable pointer
  */ 
 void 
-_dbus_connection_test_get_locks (DBusConnection *conn,
+_dbus_connection_test_get_locks (DBusConnection *connection,
                                  DBusMutex     **mutex_loc,
                                  DBusMutex     **dispatch_mutex_loc,
                                  DBusMutex     **io_path_mutex_loc,
                                  DBusCondVar   **dispatch_cond_loc,
                                  DBusCondVar   **io_path_cond_loc)
 {
-  *mutex_loc = conn->mutex;
-  *dispatch_mutex_loc = conn->dispatch_mutex;
-  *io_path_mutex_loc = conn->io_path_mutex; 
-  *dispatch_cond_loc = conn->dispatch_cond;
-  *io_path_cond_loc = conn->io_path_cond;
+  *mutex_loc = connection->mutex;
+  *dispatch_mutex_loc = connection->dispatch_mutex;
+  *io_path_mutex_loc = connection->io_path_mutex; 
+  *dispatch_cond_loc = connection->dispatch_cond;
+  *io_path_cond_loc = connection->io_path_cond;
 }
 #endif
 
@@ -578,10 +578,13 @@ _dbus_connection_message_sent (DBusConnection *connection,
   dbus_message_unref (message);
 }
 
+/** Function to be called in protected_change_watch() with refcount held */
 typedef dbus_bool_t (* DBusWatchAddFunction)     (DBusWatchList *list,
                                                   DBusWatch     *watch);
+/** Function to be called in protected_change_watch() with refcount held */
 typedef void        (* DBusWatchRemoveFunction)  (DBusWatchList *list,
                                                   DBusWatch     *watch);
+/** Function to be called in protected_change_watch() with refcount held */
 typedef void        (* DBusWatchToggleFunction)  (DBusWatchList *list,
                                                   DBusWatch     *watch,
                                                   dbus_bool_t    enabled);
@@ -696,10 +699,13 @@ _dbus_connection_toggle_watch_unlocked (DBusConnection *connection,
                           enabled);
 }
 
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef dbus_bool_t (* DBusTimeoutAddFunction)    (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout);
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef void        (* DBusTimeoutRemoveFunction) (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout);
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef void        (* DBusTimeoutToggleFunction) (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout,
                                                    dbus_bool_t      enabled);
@@ -1736,6 +1742,58 @@ _dbus_connection_open_internal (const char     *address,
   return connection;
 }
 
+/**
+ * Closes a shared OR private connection, while dbus_connection_close() can
+ * only be used on private connections. Should only be called by the
+ * dbus code that owns the connection - an owner must be known,
+ * the open/close state is like malloc/free, not like ref/unref.
+ * 
+ * @param connection the connection
+ */
+void
+_dbus_connection_close_possibly_shared (DBusConnection *connection)
+{
+  _dbus_assert (connection != NULL);
+  _dbus_assert (connection->generation == _dbus_current_generation);
+
+  CONNECTION_LOCK (connection);
+  _dbus_connection_close_possibly_shared_and_unlock (connection);
+}
+
+
+/**
+ * Like dbus_connection_send(), but assumes the connection
+ * is already locked on function entry, and unlocks before returning.
+ *
+ * @param connection the connection
+ * @param message the message to send
+ * @param client_serial return location for client serial of sent message
+ * @returns #FALSE on out-of-memory
+ */
+dbus_bool_t
+_dbus_connection_send_and_unlock (DBusConnection *connection,
+				  DBusMessage    *message,
+				  dbus_uint32_t  *client_serial)
+{
+  DBusPreallocatedSend *preallocated;
+
+  _dbus_assert (connection != NULL);
+  _dbus_assert (message != NULL);
+  
+  preallocated = _dbus_connection_preallocate_send_unlocked (connection);
+  if (preallocated == NULL)
+    {
+      CONNECTION_UNLOCK (connection);
+      return FALSE;
+    }
+
+  _dbus_connection_send_preallocated_and_unlock (connection,
+						 preallocated,
+						 message,
+						 client_serial);
+  return TRUE;
+}
+
 /** @} */
 
 /**
@@ -2062,16 +2120,6 @@ _dbus_connection_close_possibly_shared_and_unlock (DBusConnection *connection)
   dbus_connection_unref (connection);
 }
 
-void
-_dbus_connection_close_possibly_shared (DBusConnection *connection)
-{
-  _dbus_assert (connection != NULL);
-  _dbus_assert (connection->generation == _dbus_current_generation);
-
-  CONNECTION_LOCK (connection);
-  _dbus_connection_close_possibly_shared_and_unlock (connection);
-}
-
 /**
  * Closes a private connection, so no further data can be sent or received.
  * This disconnects the transport (such as a socket) underlying the
@@ -2505,30 +2553,6 @@ _dbus_connection_send_unlocked_no_update (DBusConnection *connection,
   return TRUE;
 }
 
-dbus_bool_t
-_dbus_connection_send_and_unlock (DBusConnection *connection,
-				  DBusMessage    *message,
-				  dbus_uint32_t  *client_serial)
-{
-  DBusPreallocatedSend *preallocated;
-
-  _dbus_assert (connection != NULL);
-  _dbus_assert (message != NULL);
-  
-  preallocated = _dbus_connection_preallocate_send_unlocked (connection);
-  if (preallocated == NULL)
-    {
-      CONNECTION_UNLOCK (connection);
-      return FALSE;
-    }
-
-  _dbus_connection_send_preallocated_and_unlock (connection,
-						 preallocated,
-						 message,
-						 client_serial);
-  return TRUE;
-}
-
 /**
  * Adds a message to the outgoing message queue. Does not block to
  * write the message to the network; that happens asynchronously. To
@@ -3997,7 +4021,7 @@ _dbus_connection_run_builtin_filters_unlocked_no_update (DBusConnection *connect
  * unrefs the message. Returns a status indicating whether messages/data
  * remain, more memory is needed, or all data has been processed.
  * 
- * Even if the dispatch status is #DBUS_DISPATCH_DATA_REMAINS,
+ * Even if the dispatch status is #DBUS_DISPATCH_DATA_REMAINS
  * does not necessarily dispatch a message, as the data may
  * be part of authentication or the like.
  *
diff --git a/dbus/dbus-dataslot.c b/dbus/dbus-dataslot.c
index 3e9aabfc..a84b9244 100644
--- a/dbus/dbus-dataslot.c
+++ b/dbus/dbus-dataslot.c
@@ -151,7 +151,7 @@ _dbus_data_slot_allocator_alloc (DBusDataSlotAllocator *allocator,
 /**
  * Deallocates an ID previously allocated with
  * _dbus_data_slot_allocator_alloc().  Existing data stored on
- * existing #DBusDataList objects with this ID will be freed when the
+ * existing #DBusDataSlotList objects with this ID will be freed when the
  * data list is finalized, but may not be retrieved (and may only be
  * replaced if someone else reallocates the slot).
  * The slot value is reset to -1 if this is the last unref.
diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h
index 0d1e322b..4424e8c8 100644
--- a/dbus/dbus-hash.h
+++ b/dbus/dbus-hash.h
@@ -58,6 +58,7 @@ typedef enum
   DBUS_HASH_POINTER,       /**< Hash keys are pointers. */
   DBUS_HASH_ULONG          /**< Hash keys are unsigned long. */
 } DBusHashType;
+
 DBusHashTable* _dbus_hash_table_new                (DBusHashType      type,
                                                     DBusFreeFunction  key_free_function,
                                                     DBusFreeFunction  value_free_function);
diff --git a/dbus/dbus-internals.c b/dbus/dbus-internals.c
index 2233fc68..5268ebdf 100644
--- a/dbus/dbus-internals.c
+++ b/dbus/dbus-internals.c
@@ -28,8 +28,12 @@
 #include <string.h>
 #include <stdlib.h>
 
+/* the blurb for this is "D-Bus secret" so it comes after "D-Bus low-level"
+ * which is the blurb for the DBus group, which makes Doxygen show
+ * the public API first on the index page. Yay for lame hacks.
+ */
 /**
- * @defgroup DBusInternals D-Bus internal implementation details
+ * @defgroup DBusInternals D-Bus secret internal implementation details
  * @brief Documentation useful when developing or debugging D-Bus itself.
  * 
  */
@@ -288,6 +292,7 @@ _dbus_warn_check_failed(const char *format,
 static dbus_bool_t verbose_initted = FALSE;
 static dbus_bool_t verbose = TRUE;
 
+/** Whether to show the current thread in verbose messages */
 #define PTHREAD_IN_VERBOSE 0
 #if PTHREAD_IN_VERBOSE
 #include <pthread.h>
@@ -304,6 +309,11 @@ _dbus_verbose_init (void)
     }
 }
 
+/**
+ * Implementation of dbus_is_verbose() macro if built with verbose logging
+ * enabled.
+ * @returns whether verbose logging is active.
+ */
 dbus_bool_t
 _dbus_is_verbose_real (void)
 {
diff --git a/dbus/dbus-internals.h b/dbus/dbus-internals.h
index 3c8750e9..c0422c83 100644
--- a/dbus/dbus-internals.h
+++ b/dbus/dbus-internals.h
@@ -322,8 +322,8 @@ void          _dbus_set_bad_address        (DBusError         *error,
  */
 union DBusGUID
 {
-  dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_BYTES / 4];
-  char as_bytes[DBUS_UUID_LENGTH_BYTES];
+  dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_BYTES / 4]; /**< guid as four uint32 values */
+  char as_bytes[DBUS_UUID_LENGTH_BYTES];                /**< guid as 16 single-byte values */
 };
 
 void        _dbus_generate_uuid  (DBusGUID         *uuid);
diff --git a/dbus/dbus-mainloop.c b/dbus/dbus-mainloop.c
index b3089bbc..68284474 100644
--- a/dbus/dbus-mainloop.c
+++ b/dbus/dbus-mainloop.c
@@ -905,4 +905,4 @@ _dbus_wait_for_memory (void)
   _dbus_sleep_milliseconds (_dbus_get_oom_wait ());
 }
 
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
diff --git a/dbus/dbus-mainloop.h b/dbus/dbus-mainloop.h
index cc23129b..52bcd8fc 100644
--- a/dbus/dbus-mainloop.h
+++ b/dbus/dbus-mainloop.h
@@ -70,7 +70,7 @@ dbus_bool_t _dbus_loop_dispatch       (DBusLoop            *loop);
 int  _dbus_get_oom_wait    (void);
 void _dbus_wait_for_memory (void);
 
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
 
 #endif /* DBUS_MAINLOOP_H */
 
diff --git a/dbus/dbus-marshal-header.c b/dbus/dbus-marshal-header.c
index 6df8605b..564e47b5 100644
--- a/dbus/dbus-marshal-header.c
+++ b/dbus/dbus-marshal-header.c
@@ -67,8 +67,8 @@ _DBUS_STRING_DEFINE_STATIC(_dbus_local_path_str,       DBUS_PATH_LOCAL);
 
 typedef struct
 {
-  unsigned char code;
-  unsigned char type;
+  unsigned char code; /**< the field code */
+  unsigned char type; /**< the value type */
 } HeaderFieldType;
 
 static const HeaderFieldType
diff --git a/dbus/dbus-marshal-recursive-util.c b/dbus/dbus-marshal-recursive-util.c
index e73edf49..3d4320d9 100644
--- a/dbus/dbus-marshal-recursive-util.c
+++ b/dbus/dbus-marshal-recursive-util.c
@@ -124,6 +124,9 @@ _dbus_type_reader_equal_values (const DBusTypeReader *lhs,
 }
 
 /* TESTS */
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include "dbus-test.h"
 #include "dbus-list.h"
 #include <stdio.h>
@@ -3557,4 +3560,6 @@ container_destroy (TestTypeNode *node)
     }
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* DBUS_BUILD_TESTS */
diff --git a/dbus/dbus-marshal-recursive.c b/dbus/dbus-marshal-recursive.c
index 536d4cbf..501e9a53 100644
--- a/dbus/dbus-marshal-recursive.c
+++ b/dbus/dbus-marshal-recursive.c
@@ -1116,8 +1116,8 @@ _dbus_type_reader_get_signature (const DBusTypeReader  *reader,
 
 typedef struct
 {
-  DBusString replacement;
-  int padding;
+  DBusString replacement; /**< Marshaled value including alignment padding */
+  int padding;            /**< How much of the replacement block is padding */
 } ReplacementBlock;
 
 static dbus_bool_t
diff --git a/dbus/dbus-marshal-validate-util.c b/dbus/dbus-marshal-validate-util.c
index d9beee6c..341b2762 100644
--- a/dbus/dbus-marshal-validate-util.c
+++ b/dbus/dbus-marshal-validate-util.c
@@ -23,6 +23,9 @@
 
 #include <config.h>
 #ifdef DBUS_BUILD_TESTS
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include "dbus-internals.h"
 #include "dbus-marshal-validate.h"
 #include "dbus-marshal-recursive.h"
@@ -579,4 +582,6 @@ _dbus_marshal_validate_test (void)
   return TRUE;
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* DBUS_BUILD_TESTS */
diff --git a/dbus/dbus-md5.c b/dbus/dbus-md5.c
index 079b1cc0..b7ddb5f4 100644
--- a/dbus/dbus-md5.c
+++ b/dbus/dbus-md5.c
@@ -157,7 +157,7 @@ main(int argc, char **argv)
 #define T62 /* 0xbd3af235 */ (T_MASK ^ 0x42c50dca)
 #define T63    0x2ad7d2bb
 #define T64 /* 0xeb86d391 */ (T_MASK ^ 0x14792c6e)
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
 
 static void
 md5_process(DBusMD5Context *context, const unsigned char *data /*[64]*/)
diff --git a/dbus/dbus-message-factory.c b/dbus/dbus-message-factory.c
index c3fb1bc1..db1b254d 100644
--- a/dbus/dbus-message-factory.c
+++ b/dbus/dbus-message-factory.c
@@ -22,6 +22,8 @@
  */
 #include <config.h>
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #ifdef DBUS_BUILD_TESTS
 #include "dbus-message-factory.h"
 #include "dbus-message-private.h"
@@ -1221,4 +1223,6 @@ _dbus_message_data_iter_get_and_next (DBusMessageDataIter *iter,
   return TRUE;
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* DBUS_BUILD_TESTS */
diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 9b0d7a0b..80eee1cb 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -126,6 +126,12 @@ _dbus_message_byteswap (DBusMessage *message)
   _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
 }
 
+/** byte-swap the message if it doesn't match our byte order.
+ *  Called only when we need the message in our own byte order,
+ *  normally when reading arrays of integers or doubles.
+ *  Otherwise should not be called since it would do needless
+ *  work.
+ */
 #define ensure_byte_order(message)                      \
  if (message->byte_order != DBUS_COMPILER_BYTE_ORDER)   \
    _dbus_message_byteswap (message)
@@ -1119,10 +1125,9 @@ dbus_message_unref (DBusMessage *message)
  * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
  * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
  * types are allowed and all code must silently ignore messages of
- * unknown type. DBUS_MESSAGE_TYPE_INVALID will never be returned,
+ * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned,
  * however.
  *
- *
  * @param message the message
  * @returns the type of the message
  */
diff --git a/dbus/dbus-object-tree.c b/dbus/dbus-object-tree.c
index ec83498b..e5ff7734 100644
--- a/dbus/dbus-object-tree.c
+++ b/dbus/dbus-object-tree.c
@@ -1141,6 +1141,9 @@ _dbus_decompose_path (const char*     data,
 /** @} */
 
 #ifdef DBUS_BUILD_TESTS
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include "dbus-test.h"
 #include <stdio.h>
 
@@ -1926,4 +1929,6 @@ _dbus_object_tree_test (void)
   return TRUE;
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* DBUS_BUILD_TESTS */
diff --git a/dbus/dbus-pending-call.c b/dbus/dbus-pending-call.c
index ec57395e..79dacc8a 100644
--- a/dbus/dbus-pending-call.c
+++ b/dbus/dbus-pending-call.c
@@ -44,7 +44,14 @@
  *
  * Opaque object representing a reply message that we're waiting for.
  */
+
+/**
+ * shorter and more visible way to write _dbus_connection_lock()
+ */
 #define CONNECTION_LOCK(connection)   _dbus_connection_lock(connection)
+/**
+ * shorter and more visible way to write _dbus_connection_unlock()
+ */
 #define CONNECTION_UNLOCK(connection) _dbus_connection_unlock(connection)
 
 struct DBusPendingCall
@@ -189,6 +196,13 @@ _dbus_pending_call_complete (DBusPendingCall *pending)
     }
 }
 
+/**
+ * If the pending call hasn't been timed out, add its timeout
+ * error reply to the connection's incoming message queue.
+ *
+ * @param pending the pending call
+ * @param connection the connection the call was sent to
+ */
 void
 _dbus_pending_call_queue_timeout_error_unlocked (DBusPendingCall *pending, 
                                                  DBusConnection  *connection)
diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h
index 4cfb6d16..a36e67c3 100644
--- a/dbus/dbus-protocol.h
+++ b/dbus/dbus-protocol.h
@@ -31,6 +31,9 @@
 
 #ifdef  __cplusplus
 extern "C" {
+#if 0
+} /* avoids confusing emacs indentation */
+#endif
 #endif
 
 /* Normally docs are in .c files, but there isn't a .c file for this. */
@@ -52,62 +55,113 @@ extern "C" {
 /** Protocol version */
 #define DBUS_MAJOR_PROTOCOL_VERSION 1
 
-/** Never a legitimate type */
+/** Type code that is never equal to a legitimate type code */
 #define DBUS_TYPE_INVALID       ((int) '\0')
+/** #DBUS_TYPE_INVALID as a string literal instead of a int literal */
 #define DBUS_TYPE_INVALID_AS_STRING        "\0"
 
 /* Primitive types */
+/** Type code marking an 8-bit unsigned integer */
 #define DBUS_TYPE_BYTE          ((int) 'y')
+/** #DBUS_TYPE_BYTE as a string literal instead of a int literal */
 #define DBUS_TYPE_BYTE_AS_STRING           "y"
+/** Type code marking a boolean */
 #define DBUS_TYPE_BOOLEAN       ((int) 'b')
+/** #DBUS_TYPE_BOOLEAN as a string literal instead of a int literal */
 #define DBUS_TYPE_BOOLEAN_AS_STRING        "b"
+/** Type code marking a 16-bit signed integer */
 #define DBUS_TYPE_INT16         ((int) 'n')
+/** #DBUS_TYPE_INT16 as a string literal instead of a int literal */
 #define DBUS_TYPE_INT16_AS_STRING          "n"
+/** Type code marking a 16-bit unsigned integer */
 #define DBUS_TYPE_UINT16        ((int) 'q')
+/** #DBUS_TYPE_UINT16 as a string literal instead of a int literal */
 #define DBUS_TYPE_UINT16_AS_STRING         "q"
+/** Type code marking a 32-bit signed integer */
 #define DBUS_TYPE_INT32         ((int) 'i')
+/** #DBUS_TYPE_INT32 as a string literal instead of a int literal */
 #define DBUS_TYPE_INT32_AS_STRING          "i"
+/** Type code marking a 32-bit unsigned integer */
 #define DBUS_TYPE_UINT32        ((int) 'u')
+/** #DBUS_TYPE_UINT32 as a string literal instead of a int literal */
 #define DBUS_TYPE_UINT32_AS_STRING         "u"
+/** Type code marking a 64-bit signed integer */
 #define DBUS_TYPE_INT64         ((int) 'x')
+/** #DBUS_TYPE_INT64 as a string literal instead of a int literal */
 #define DBUS_TYPE_INT64_AS_STRING          "x"
+/** Type code marking a 64-bit unsigned integer */
 #define DBUS_TYPE_UINT64        ((int) 't')
+/** #DBUS_TYPE_UINT64 as a string literal instead of a int literal */
 #define DBUS_TYPE_UINT64_AS_STRING         "t"
+/** Type code marking an 8-byte double in IEEE 754 format */
 #define DBUS_TYPE_DOUBLE        ((int) 'd')
+/** #DBUS_TYPE_DOUBLE as a string literal instead of a int literal */
 #define DBUS_TYPE_DOUBLE_AS_STRING         "d"
+/** Type code marking a UTF-8 encoded, nul-terminated Unicode string */
 #define DBUS_TYPE_STRING        ((int) 's')
+/** #DBUS_TYPE_STRING as a string literal instead of a int literal */
 #define DBUS_TYPE_STRING_AS_STRING         "s"
+/** Type code marking a D-Bus object path */
 #define DBUS_TYPE_OBJECT_PATH   ((int) 'o')
+/** #DBUS_TYPE_OBJECT_PATH as a string literal instead of a int literal */
 #define DBUS_TYPE_OBJECT_PATH_AS_STRING    "o"
+/** Type code marking a D-Bus type signature */
 #define DBUS_TYPE_SIGNATURE     ((int) 'g')
+/** #DBUS_TYPE_SIGNATURE as a string literal instead of a int literal */
 #define DBUS_TYPE_SIGNATURE_AS_STRING      "g"
 
 /* Compound types */
+/** Type code marking a D-Bus array type */
 #define DBUS_TYPE_ARRAY         ((int) 'a')
+/** #DBUS_TYPE_ARRAY as a string literal instead of a int literal */
 #define DBUS_TYPE_ARRAY_AS_STRING          "a"
+/** Type code marking a D-Bus variant type */
 #define DBUS_TYPE_VARIANT       ((int) 'v')
+/** #DBUS_TYPE_VARIANT as a string literal instead of a int literal */
 #define DBUS_TYPE_VARIANT_AS_STRING        "v"
 
 /** STRUCT and DICT_ENTRY are sort of special since their codes can't
  * appear in a type string, instead
  * DBUS_STRUCT_BEGIN_CHAR/DBUS_DICT_ENTRY_BEGIN_CHAR have to appear
  */
+/** Type code used to represent a struct; however, this type code does not appear
+ * in type signatures, instead #DBUS_STRUCT_BEGIN_CHAR and #DBUS_STRUCT_END_CHAR will
+ * appear in a signature.
+ */
 #define DBUS_TYPE_STRUCT        ((int) 'r')
+/** #DBUS_TYPE_STRUCT as a string literal instead of a int literal */
 #define DBUS_TYPE_STRUCT_AS_STRING         "r"
+/** Type code used to represent a dict entry; however, this type code does not appear
+ * in type signatures, instead #DBUS_DICT_ENTRY_BEGIN_CHAR and #DBUS_DICT_ENTRY_END_CHAR will
+ * appear in a signature.
+ */
 #define DBUS_TYPE_DICT_ENTRY    ((int) 'e')
+/** #DBUS_TYPE_DICT_ENTRY as a string literal instead of a int literal */
 #define DBUS_TYPE_DICT_ENTRY_AS_STRING     "e"
 
-/** Does not count INVALID */
+/** Does not include #DBUS_TYPE_INVALID, #DBUS_STRUCT_BEGIN_CHAR, #DBUS_STRUCT_END_CHAR,
+ * #DBUS_DICT_ENTRY_BEGIN_CHAR, or #DBUS_DICT_ENTRY_END_CHAR - i.e. it is the number of
+ * valid types, not the number of distinct characters that may appear in a type signature.
+ */
 #define DBUS_NUMBER_OF_TYPES    (16)
 
 /* characters other than typecodes that appear in type signatures */
+
+/** Code marking the start of a struct type in a type signature */
 #define DBUS_STRUCT_BEGIN_CHAR   ((int) '(')
+/** #DBUS_STRUCT_BEGIN_CHAR as a string literal instead of a int literal */
 #define DBUS_STRUCT_BEGIN_CHAR_AS_STRING   "("
+/** Code marking the end of a struct type in a type signature */
 #define DBUS_STRUCT_END_CHAR     ((int) ')')
+/** #DBUS_STRUCT_END_CHAR a string literal instead of a int literal */
 #define DBUS_STRUCT_END_CHAR_AS_STRING     ")"
+/** Code marking the start of a dict entry type in a type signature */
 #define DBUS_DICT_ENTRY_BEGIN_CHAR   ((int) '{')
+/** #DBUS_DICT_ENTRY_BEGIN_CHAR as a string literal instead of a int literal */
 #define DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING   "{"
+/** Code marking the end of a dict entry type in a type signature */
 #define DBUS_DICT_ENTRY_END_CHAR     ((int) '}')
+/** #DBUS_DICT_ENTRY_END_CHAR as a string literal instead of a int literal */
 #define DBUS_DICT_ENTRY_END_CHAR_AS_STRING     "}"
 
 /** Max length in bytes of a bus name, interface, or member (not object
@@ -160,27 +214,74 @@ extern "C" {
 #define DBUS_MAXIMUM_TYPE_RECURSION_DEPTH 32
 
 /* Types of message */
+
+/** This value is never a valid message type, see dbus_message_get_type() */
 #define DBUS_MESSAGE_TYPE_INVALID       0
+/** Message type of a method call message, see dbus_message_get_type() */
 #define DBUS_MESSAGE_TYPE_METHOD_CALL   1
+/** Message type of a method return message, see dbus_message_get_type() */
 #define DBUS_MESSAGE_TYPE_METHOD_RETURN 2
+/** Message type of an error reply message, see dbus_message_get_type() */
 #define DBUS_MESSAGE_TYPE_ERROR         3
+/** Message type of a signal message, see dbus_message_get_type() */
 #define DBUS_MESSAGE_TYPE_SIGNAL        4
 
 /* Header flags */
+
+/** If set, this flag means that the sender of a message does not care about getting
+ * a reply, so the recipient need not send one. See dbus_message_set_no_reply().
+ */
 #define DBUS_HEADER_FLAG_NO_REPLY_EXPECTED 0x1
+/**
+ * If set, this flag means that even if the message bus knows how to start an owner for
+ * the destination bus name (see dbus_message_set_destination()), it should not
+ * do so. If this flag is not set, the bus may launch a program to process the
+ * message.
+ */
 #define DBUS_HEADER_FLAG_NO_AUTO_START     0x2
 
 /* Header fields */
+
+/** Not equal to any valid header field code */
 #define DBUS_HEADER_FIELD_INVALID        0
+/** Header field code for the path - the path is the object emitting a signal or the object receiving a method call.
+ * See dbus_message_set_path().
+ */
 #define DBUS_HEADER_FIELD_PATH           1
+/** Header field code for the interface containing a member (method or signal).
+ * See dbus_message_set_interface().
+ */
 #define DBUS_HEADER_FIELD_INTERFACE      2
+/** Header field code for a member (method or signal). See dbus_message_set_member(). */
 #define DBUS_HEADER_FIELD_MEMBER         3
+/** Header field code for an error name (found in #DBUS_MESSAGE_TYPE_ERROR messages).
+ * See dbus_message_set_error_name().
+ */
 #define DBUS_HEADER_FIELD_ERROR_NAME     4
+/** Header field code for a reply serial, used to match a #DBUS_MESSAGE_TYPE_METHOD_RETURN message with the
+ * message that it's a reply to. See dbus_message_set_reply_serial().
+ */
 #define DBUS_HEADER_FIELD_REPLY_SERIAL   5
+/**
+ * Header field code for the destination bus name of a message. See dbus_message_set_destination().
+ */
 #define DBUS_HEADER_FIELD_DESTINATION    6
+/**
+ * Header field code for the sender of a message; usually initialized by the message bus.
+ * See dbus_message_set_sender().
+ */
 #define DBUS_HEADER_FIELD_SENDER         7
+/**
+ * Header field code for the type signature of a message.
+ */
 #define DBUS_HEADER_FIELD_SIGNATURE      8
 
+/**
+ * Value of the highest-numbered header field code, can be used to determine
+ * the size of an array indexed by header field code. Remember though
+ * that unknown codes must be ignored, so check for that before
+ * indexing the array.
+ */
 #define DBUS_HEADER_FIELD_LAST DBUS_HEADER_FIELD_SIGNATURE
 
 /** Header format is defined as a signature:
@@ -224,47 +325,88 @@ extern "C" {
  * Also, don't change the formatting since that will break the sed
  * script.
  */
+/** A generic error; "something went wrong" - see the error message for more. */
 #define DBUS_ERROR_FAILED                     "org.freedesktop.DBus.Error.Failed"
+/** There was not enough memory to complete an operation. */
 #define DBUS_ERROR_NO_MEMORY                  "org.freedesktop.DBus.Error.NoMemory"
+/** The bus doesn't know how to launch a service to supply the bus name you wanted. */
 #define DBUS_ERROR_SERVICE_UNKNOWN            "org.freedesktop.DBus.Error.ServiceUnknown"
+/** The bus name you referenced doesn't exist (i.e. no application owns it). */
 #define DBUS_ERROR_NAME_HAS_NO_OWNER          "org.freedesktop.DBus.Error.NameHasNoOwner"
+/** No reply to a message expecting one, usually means a timeout occurred. */
 #define DBUS_ERROR_NO_REPLY                   "org.freedesktop.DBus.Error.NoReply"
+/** Something went wrong reading or writing to a socket, for example. */
 #define DBUS_ERROR_IO_ERROR                   "org.freedesktop.DBus.Error.IOError"
+/** A D-Bus bus address was malformed. */
 #define DBUS_ERROR_BAD_ADDRESS                "org.freedesktop.DBus.Error.BadAddress"
+/** Requested operation isn't supported (like ENOSYS on UNIX). */
 #define DBUS_ERROR_NOT_SUPPORTED              "org.freedesktop.DBus.Error.NotSupported"
+/** Some limited resource is exhausted. */
 #define DBUS_ERROR_LIMITS_EXCEEDED            "org.freedesktop.DBus.Error.LimitsExceeded"
+/** Security restrictions don't allow doing what you're trying to do. */
 #define DBUS_ERROR_ACCESS_DENIED              "org.freedesktop.DBus.Error.AccessDenied"
+/** Authentication didn't work. */
 #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. */
 #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"
+/** Can't bind a socket since its address is in use (i.e. EADDRINUSE). */
 #define DBUS_ERROR_ADDRESS_IN_USE             "org.freedesktop.DBus.Error.AddressInUse"
+/** The connection is disconnected and you're trying to use it. */
 #define DBUS_ERROR_DISCONNECTED               "org.freedesktop.DBus.Error.Disconnected"
+/** Invalid arguments passed to a method call. */
 #define DBUS_ERROR_INVALID_ARGS               "org.freedesktop.DBus.Error.InvalidArgs"
+/** Missing file. */
 #define DBUS_ERROR_FILE_NOT_FOUND             "org.freedesktop.DBus.Error.FileNotFound"
+/** Existing file and the operation you're using does not silently overwrite. */
 #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 */
 #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"
+/** The match rule isn't syntactically valid. */
 #define DBUS_ERROR_MATCH_RULE_INVALID         "org.freedesktop.DBus.Error.MatchRuleInvalid"
+/** While starting a new process, the exec() call failed. */
 #define DBUS_ERROR_SPAWN_EXEC_FAILED          "org.freedesktop.DBus.Error.Spawn.ExecFailed"
+/** While starting a new process, the fork() call failed. */
 #define DBUS_ERROR_SPAWN_FORK_FAILED          "org.freedesktop.DBus.Error.Spawn.ForkFailed"
+/** While starting a new process, the child exited with a status code. */
 #define DBUS_ERROR_SPAWN_CHILD_EXITED         "org.freedesktop.DBus.Error.Spawn.ChildExited"
+/** While starting a new process, the child exited on a signal. */
 #define DBUS_ERROR_SPAWN_CHILD_SIGNALED       "org.freedesktop.DBus.Error.Spawn.ChildSignaled"
+/** While starting a new process, something went wrong. */
 #define DBUS_ERROR_SPAWN_FAILED               "org.freedesktop.DBus.Error.Spawn.Failed"
+/** Tried to get a UNIX process ID and it wasn't available. */
 #define DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN    "org.freedesktop.DBus.Error.UnixProcessIdUnknown"
+/** A type signature is not valid. */
 #define DBUS_ERROR_INVALID_SIGNATURE          "org.freedesktop.DBus.Error.InvalidSignature"
+/** A file contains invalid syntax or is otherwise broken. */
 #define DBUS_ERROR_INVALID_FILE_CONTENT       "org.freedesktop.DBus.Error.InvalidFileContent"
+/** Asked for SELinux security context and it wasn't available. */
 #define DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN    "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown"
 
+/* XML introspection format */
+
+/** XML namespace of the introspection format version 1.0 */
 #define DBUS_INTROSPECT_1_0_XML_NAMESPACE         "http://www.freedesktop.org/standards/dbus"
+/** XML public identifier of the introspection format version 1.0 */
 #define DBUS_INTROSPECT_1_0_XML_PUBLIC_IDENTIFIER "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+/** XML system identifier of the introspection format version 1.0 */
 #define DBUS_INTROSPECT_1_0_XML_SYSTEM_IDENTIFIER "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"
+/** XML document type declaration of the introspection format version 1.0 */
 #define DBUS_INTROSPECT_1_0_XML_DOCTYPE_DECL_NODE "<!DOCTYPE node PUBLIC \""DBUS_INTROSPECT_1_0_XML_PUBLIC_IDENTIFIER"\"\n\""DBUS_INTROSPECT_1_0_XML_SYSTEM_IDENTIFIER"\">\n"
 
 /** @} */
 
 #ifdef __cplusplus
+#if 0
+{ /* avoids confusing emacs indentation */
+#endif
 }
 #endif
 
diff --git a/dbus/dbus-server-debug-pipe.c b/dbus/dbus-server-debug-pipe.c
index 0fb45c63..27115caa 100644
--- a/dbus/dbus-server-debug-pipe.c
+++ b/dbus/dbus-server-debug-pipe.c
@@ -329,7 +329,7 @@ _dbus_transport_debug_pipe_new (const char     *server_name,
  * Sets error if the result is not OK.
  * 
  * @param entry an address entry
- * @param a new DBusServer, or #NULL on failure.
+ * @param server_p location to store a new DBusServer, or #NULL on failure.
  * @param error location to store rationale for failure on bad address
  * @returns the outcome
  * 
@@ -376,6 +376,14 @@ _dbus_server_listen_debug_pipe (DBusAddressEntry *entry,
     }
 }
 
+/**
+ * Opens a debug pipe transport, used in the test suite.
+ * 
+ * @param entry the address entry to try opening as debug-pipe
+ * @param transport_p return location for the opened transport
+ * @param error error to be set
+ * @returns result of the attempt
+ */
 DBusTransportOpenResult
 _dbus_transport_open_debug_pipe (DBusAddressEntry  *entry,
                                  DBusTransport    **transport_p,
diff --git a/dbus/dbus-server-unix.c b/dbus/dbus-server-unix.c
index ffc68709..6dd28bcf 100644
--- a/dbus/dbus-server-unix.c
+++ b/dbus/dbus-server-unix.c
@@ -43,7 +43,7 @@
  * Sets error if the result is not OK.
  * 
  * @param entry an address entry
- * @param a new DBusServer, or #NULL on failure.
+ * @param server_p location to store a new DBusServer, or #NULL on failure.
  * @param error location to store rationale for failure on bad address
  * @returns the outcome
  * 
diff --git a/dbus/dbus-server.c b/dbus/dbus-server.c
index 059c8485..b54133bb 100644
--- a/dbus/dbus-server.c
+++ b/dbus/dbus-server.c
@@ -194,10 +194,13 @@ _dbus_server_finalize_base (DBusServer *server)
 }
 
 
+/** Function to be called in protected_change_watch() with refcount held */
 typedef dbus_bool_t (* DBusWatchAddFunction)     (DBusWatchList *list,
                                                   DBusWatch     *watch);
+/** Function to be called in protected_change_watch() with refcount held */
 typedef void        (* DBusWatchRemoveFunction)  (DBusWatchList *list,
                                                   DBusWatch     *watch);
+/** Function to be called in protected_change_watch() with refcount held */
 typedef void        (* DBusWatchToggleFunction)  (DBusWatchList *list,
                                                   DBusWatch     *watch,
                                                   dbus_bool_t    enabled);
@@ -307,11 +310,13 @@ _dbus_server_toggle_watch (DBusServer  *server,
                           enabled);
 }
 
-
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef dbus_bool_t (* DBusTimeoutAddFunction)    (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout);
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef void        (* DBusTimeoutRemoveFunction) (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout);
+/** Function to be called in protected_change_timeout() with refcount held */
 typedef void        (* DBusTimeoutToggleFunction) (DBusTimeoutList *list,
                                                    DBusTimeout     *timeout,
                                                    dbus_bool_t      enabled);
diff --git a/dbus/dbus-sha.c b/dbus/dbus-sha.c
index b386e452..4a5b8d18 100644
--- a/dbus/dbus-sha.c
+++ b/dbus/dbus-sha.c
@@ -157,7 +157,7 @@ effort (for example the reengineering of a great many Capstone chips).
 #define subRound(a, b, c, d, e, f, k, data) \
    ( e += ROTL( 5, a ) + f( b, c, d ) + k + data, b = ROTL( 30, b ) )
 
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
 
 /* Perform the SHA transformation.  Note that this code, like MD5, seems to
    break some optimizing compilers due to the complexity of the expressions
diff --git a/dbus/dbus-shared.h b/dbus/dbus-shared.h
index 357327da..78d305ef 100644
--- a/dbus/dbus-shared.h
+++ b/dbus/dbus-shared.h
@@ -30,6 +30,9 @@
 
 #ifdef  __cplusplus
 extern "C" {
+#if 0
+} /* avoids confusing emacs indentation */
+#endif
 #endif
 
 /* Normally docs are in .c files, but there isn't a .c file for this. */
@@ -44,6 +47,9 @@ extern "C" {
  */
 
 
+/**
+ * Well-known bus types. See dbus_bus_get().
+ */
 typedef enum
 {
   DBUS_BUS_SESSION,    /**< The login session bus */
@@ -51,26 +57,37 @@ typedef enum
   DBUS_BUS_STARTER     /**< The bus that started us, if any */
 } DBusBusType;
 
+/**
+ * Results that a message handler can return.
+ */
 typedef enum
 {
-  DBUS_HANDLER_RESULT_HANDLED,         /**< Message has had its effect */ 
-  DBUS_HANDLER_RESULT_NOT_YET_HANDLED, /**< Message has not had any effect */
-  DBUS_HANDLER_RESULT_NEED_MEMORY      /**< Need more memory to return another result */
+  DBUS_HANDLER_RESULT_HANDLED,         /**< Message has had its effect - no need to run more handlers. */ 
+  DBUS_HANDLER_RESULT_NOT_YET_HANDLED, /**< Message has not had any effect - see if other handlers want it. */
+  DBUS_HANDLER_RESULT_NEED_MEMORY      /**< Need more memory in order to return #DBUS_HANDLER_RESULT_HANDLED or #DBUS_HANDLER_RESULT_NOT_YET_HANDLED. Please try again later with more memory. */
 } DBusHandlerResult;
 
-/* Services */
+/* Bus names */
+
+/** The bus name used to talk to the bus itself. */
 #define DBUS_SERVICE_DBUS      "org.freedesktop.DBus"
 
 /* Paths */
+/** The object path used to talk to the bus itself. */
 #define DBUS_PATH_DBUS  "/org/freedesktop/DBus"
+/** The object path used in local/in-process-generated messages. */
 #define DBUS_PATH_LOCAL "/org/freedesktop/DBus/Local"
 
 /* Interfaces, these #define don't do much other than
  * catch typos at compile time
  */
+/** The interface exported by the object with #DBUS_SERVICE_DBUS and #DBUS_PATH_DBUS */
 #define DBUS_INTERFACE_DBUS           "org.freedesktop.DBus"
+/** The interface supported by introspectable objects */
 #define DBUS_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable"
+/** The interface supported by objects with properties */
 #define DBUS_INTERFACE_PROPERTIES     "org.freedesktop.DBus.Properties"
+/** The interface supported by most dbus peers */
 #define DBUS_INTERFACE_PEER           "org.freedesktop.DBus.Peer"
 
 /** This is a special interface whose methods can only be invoked
@@ -102,6 +119,9 @@ typedef enum
 /** @} */
 
 #ifdef __cplusplus
+#if 0
+{ /* avoids confusing emacs indentation */
+#endif
 }
 #endif
 
diff --git a/dbus/dbus-signature.c b/dbus/dbus-signature.c
index 2852ed4d..5ac1afa1 100644
--- a/dbus/dbus-signature.c
+++ b/dbus/dbus-signature.c
@@ -29,9 +29,9 @@
 
 typedef struct
 { 
-  const char *pos;
-  unsigned int finished : 1;
-  unsigned int in_array : 1;
+  const char *pos;           /**< current position in the signature string */
+  unsigned int finished : 1; /**< true if we are at the end iter */
+  unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
 } DBusSignatureRealIter;
 
 /**
diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c
index 86cb986f..bfacb24e 100644
--- a/dbus/dbus-string.c
+++ b/dbus/dbus-string.c
@@ -2011,7 +2011,7 @@ _dbus_string_skip_white_reverse (const DBusString *str,
  * @todo owen correctly notes that this is a stupid function (it was
  * written purely for test code,
  * e.g. dbus-message-builder.c). Probably should be enforced as test
- * code only with #ifdef DBUS_BUILD_TESTS
+ * code only with ifdef DBUS_BUILD_TESTS
  * 
  * @param source the source string
  * @param dest the destination string (contents are replaced)
diff --git a/dbus/dbus-sysdeps-unix.c b/dbus/dbus-sysdeps-unix.c
index aa0de381..c8a349cc 100644
--- a/dbus/dbus-sysdeps-unix.c
+++ b/dbus/dbus-sysdeps-unix.c
@@ -107,6 +107,13 @@ _dbus_open_tcp_socket (int              *fd,
   return _dbus_open_socket(fd, AF_INET, SOCK_STREAM, 0, error);
 }
 
+/**
+ * Opens a UNIX domain socket (as in the socket() call).
+ * Does not bind the socket.
+ * @param fd return location for socket descriptor
+ * @param error return location for an error
+ * @returns #FALSE if error is set
+ */
 dbus_bool_t
 _dbus_open_unix_socket (int              *fd,
                         DBusError        *error)
@@ -114,6 +121,14 @@ _dbus_open_unix_socket (int              *fd,
   return _dbus_open_socket(fd, PF_UNIX, SOCK_STREAM, 0, error);
 }
 
+/**
+ * Closes a socket. Should not be used on non-socket
+ * file descriptors or handles.
+ *
+ * @param fd the socket
+ * @param error return location for an error
+ * @returns #FALSE if error is set
+ */
 dbus_bool_t 
 _dbus_close_socket (int               fd,
                     DBusError        *error)
@@ -121,6 +136,15 @@ _dbus_close_socket (int               fd,
   return _dbus_close (fd, error);
 }
 
+/**
+ * Like _dbus_read(), but only works on sockets so is
+ * available on Windows.
+ *
+ * @param fd the socket
+ * @param buffer string to append data to
+ * @param count max amount of data to read
+ * @returns number of bytes appended to the string
+ */
 int
 _dbus_read_socket (int               fd,
                    DBusString       *buffer,
@@ -129,6 +153,16 @@ _dbus_read_socket (int               fd,
   return _dbus_read (fd, buffer, count);
 }
 
+/**
+ * Like _dbus_write(), but only supports sockets
+ * and is thus available on Windows.
+ *
+ * @param fd the file descriptor to write
+ * @param buffer the buffer to write data from
+ * @param start the first byte in the buffer to write
+ * @param len the number of bytes to try to write
+ * @returns the number of bytes written or -1 on error
+ */
 int
 _dbus_write_socket (int               fd,
                     const DBusString *buffer,
@@ -138,6 +172,19 @@ _dbus_write_socket (int               fd,
   return _dbus_write (fd, buffer, start, len);
 }
 
+/**
+ * Like _dbus_write_two() but only works on sockets and is thus
+ * available on Windows.
+ * 
+ * @param fd the file descriptor
+ * @param buffer1 first buffer
+ * @param start1 first byte to write in first buffer
+ * @param len1 number of bytes to write from first buffer
+ * @param buffer2 second buffer, or #NULL
+ * @param start2 first byte to write in second buffer
+ * @param len2 number of bytes to write in second buffer
+ * @returns total bytes written from both buffers, or -1 on error
+ */
 int
 _dbus_write_socket_two (int               fd,
                         const DBusString *buffer1,
@@ -157,9 +204,12 @@ _dbus_write_socket_two (int               fd,
  * the data it reads to the DBusString buffer. It appends
  * up to the given count, and returns the same value
  * and same errno as read(). The only exception is that
- * _dbus_read() handles EINTR for you. _dbus_read() can
+ * _dbus_read() handles EINTR for you. Also, _dbus_read() can
  * return ENOMEM, even though regular UNIX read doesn't.
  *
+ * Unlike _dbus_read_socket(), _dbus_read() is not available
+ * on Windows.
+ * 
  * @param fd the file descriptor to read from
  * @param buffer the buffer to append data to
  * @param count the amount of data to read
@@ -2441,7 +2491,7 @@ _dbus_get_autolaunch_address (DBusString *address,
  * we might want to use the registry instead of a file for
  * this, and I'm not sure how we'd ensure the uuid gets created.
  *
- * @param guid to init with the machine's uuid
+ * @param machine_id guid to init with the machine's uuid
  * @param create_if_not_found try to create the uuid if it doesn't exist
  * @param error the error return
  * @returns #FALSE if the error is set
diff --git a/dbus/dbus-transport-socket.c b/dbus/dbus-transport-socket.c
index 183604b7..76a6fcfb 100644
--- a/dbus/dbus-transport-socket.c
+++ b/dbus/dbus-transport-socket.c
@@ -1258,6 +1258,14 @@ error:
   return NULL;
 }
 
+/**
+ * Opens a TCP socket transport.
+ * 
+ * @param entry the address entry to try opening as a tcp transport.
+ * @param transport_p return location for the opened transport
+ * @param error error to be set
+ * @returns result of the attempt
+ */
 DBusTransportOpenResult
 _dbus_transport_open_socket(DBusAddressEntry  *entry,
                             DBusTransport    **transport_p,                            
diff --git a/dbus/dbus-transport-unix.c b/dbus/dbus-transport-unix.c
index 40b27eae..16239e61 100644
--- a/dbus/dbus-transport-unix.c
+++ b/dbus/dbus-transport-unix.c
@@ -108,6 +108,14 @@ _dbus_transport_new_for_domain_socket (const char     *path,
   return NULL;
 }
 
+/**
+ * Opens platform specific transport types.
+ * 
+ * @param entry the address entry to try opening
+ * @param transport_p return location for the opened transport
+ * @param error error to be set
+ * @returns result of the attempt
+ */
 DBusTransportOpenResult
 _dbus_transport_open_platform_specific (DBusAddressEntry  *entry,
                                         DBusTransport    **transport_p,
diff --git a/dbus/dbus-types.h b/dbus/dbus-types.h
index d45c2516..81943dfd 100644
--- a/dbus/dbus-types.h
+++ b/dbus/dbus-types.h
@@ -85,6 +85,8 @@ typedef dbus_uint32_t  dbus_bool_t;
  * C99 requires a 64-bit type and most likely all interesting
  * compilers support one. GLib for example flat-out requires
  * a 64-bit type.
+ *
+ * You probably want to just assume #DBUS_HAVE_INT64 is always defined.
  */
 
 /**
@@ -96,6 +98,8 @@ typedef dbus_uint32_t  dbus_bool_t;
  * C99 requires a 64-bit type and most likely all interesting
  * compilers support one. GLib for example flat-out requires
  * a 64-bit type.
+ * 
+ * You probably want to just assume #DBUS_HAVE_INT64 is always defined.
  */
 
 /**
diff --git a/dbus/dbus-uuidgen.c b/dbus/dbus-uuidgen.c
index 8da83960..0d1f28c0 100644
--- a/dbus/dbus-uuidgen.c
+++ b/dbus/dbus-uuidgen.c
@@ -70,7 +70,7 @@ return_uuid (DBusGUID   *uuid,
  * @param uuid_p out param to return the uuid
  * @param create_if_not_found whether to create it if not already there
  * @param error error return
- * @param returns #FALSE if error is set
+ * @returns #FALSE if error is set
  */
 dbus_bool_t
 dbus_internal_do_not_use_get_uuid (const char *filename,
@@ -109,7 +109,7 @@ dbus_internal_do_not_use_get_uuid (const char *filename,
  * the libdbus soname.
  *
  * @param uuid_p out param to return the uuid
- * @param returns #FALSE if no memory
+ * @returns #FALSE if no memory
  */
 dbus_bool_t
 dbus_internal_do_not_use_create_uuid (char      **uuid_p)