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
	and thus pretty simple to resolve.

21 files changed, 159 insertions, 15 deletions

diff --git a/ChangeLog b/ChangeLog
index 5b0c320d..dc84b989 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,11 @@
 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
+	and thus pretty simple to resolve.
+	
+2006-10-21  Havoc Pennington  <hp@redhat.com>
 	
 	* dbus/dbus-macros.h: add DBUS_GNUC_DEPRECATED macro
 
diff --git a/dbus/dbus-address.h b/dbus/dbus-address.h
index b82495d0..8940be5b 100644
--- a/dbus/dbus-address.h
+++ b/dbus/dbus-address.h
@@ -30,6 +30,13 @@
 #include <dbus/dbus-types.h>
 #include <dbus/dbus-errors.h>
 
+DBUS_BEGIN_DECLS
+
+/**
+ * @addtogroup DBusAddress
+ * @{
+ */
+
 typedef struct DBusAddressEntry DBusAddressEntry;
 
 dbus_bool_t dbus_parse_address            (const char         *address,
@@ -45,5 +52,9 @@ char* dbus_address_escape_value   (const char *value);
 char* dbus_address_unescape_value (const char *value,
                                    DBusError  *error);
 
+/** @} */
+
+DBUS_END_DECLS
+
 #endif /* DBUS_ADDRESS_H */
 
diff --git a/dbus/dbus-bus.h b/dbus/dbus-bus.h
index b4933af3..2c697abd 100644
--- a/dbus/dbus-bus.h
+++ b/dbus/dbus-bus.h
@@ -31,6 +31,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusBus
+ * @{
+ */
+
 DBusConnection *dbus_bus_get              (DBusBusType     type,
 					   DBusError      *error);
 DBusConnection *dbus_bus_get_private      (DBusBusType     type,
@@ -70,6 +75,8 @@ void            dbus_bus_remove_match     (DBusConnection *connection,
 
 void           _dbus_bus_notify_shared_connection_disconnected_unlocked (DBusConnection *connection);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_BUS_H */
diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h
index 1e78c1f3..465cdbf4 100644
--- a/dbus/dbus-connection.h
+++ b/dbus/dbus-connection.h
@@ -34,6 +34,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusConnection
+ * @{
+ */
+
 typedef struct DBusWatch DBusWatch;
 typedef struct DBusTimeout DBusTimeout;
 typedef struct DBusPreallocatedSend DBusPreallocatedSend;
@@ -262,6 +267,8 @@ dbus_bool_t dbus_connection_get_socket             (DBusConnection
 
 char*       dbus_get_local_machine_id              (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_CONNECTION_H */
diff --git a/dbus/dbus-errors.h b/dbus/dbus-errors.h
index 2438cb26..3ea12f0c 100644
--- a/dbus/dbus-errors.h
+++ b/dbus/dbus-errors.h
@@ -33,6 +33,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusErrors
+ * @{
+ */
+
 typedef struct DBusError DBusError;
 
 /**
@@ -67,6 +72,8 @@ dbus_bool_t dbus_error_has_name  (const DBusError *error,
                                   const char      *name);
 dbus_bool_t dbus_error_is_set    (const DBusError *error);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_ERROR_H */
diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h
index 4424e8c8..71f2f6a4 100644
--- a/dbus/dbus-hash.h
+++ b/dbus/dbus-hash.h
@@ -29,6 +29,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusHashTable
+ * @{
+ */
+
 /** Hash iterator object. The iterator is on the stack, but its real
  * fields are hidden privately.
  */
@@ -128,6 +133,7 @@ void                  _dbus_hash_table_insert_string_preallocated (DBusHashTable
                                                                    char                 *key,
                                                                    void                 *value);
 
+/** @} */
 
 DBUS_END_DECLS
 
diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h
index 0074c437..3436b6ce 100644
--- a/dbus/dbus-marshal-validate.h
+++ b/dbus/dbus-marshal-validate.h
@@ -31,6 +31,12 @@
 #endif
 
 /**
+ * @addtogroup DBusMarshal
+ *
+ * @{
+ */
+
+/**
  * This is used rather than a bool for high visibility
  */
 typedef enum
@@ -49,11 +55,11 @@ typedef enum
 typedef enum
 {
 #define _DBUS_NEGATIVE_VALIDITY_COUNT 4
-  DBUS_VALIDITY_UNKNOWN_OOM_ERROR = -4,
+  DBUS_VALIDITY_UNKNOWN_OOM_ERROR = -4, /**< can't determine validity due to OOM */
   DBUS_INVALID_FOR_UNKNOWN_REASON = -3,
   DBUS_VALID_BUT_INCOMPLETE = -2,
   DBUS_VALIDITY_UNKNOWN = -1,
-  DBUS_VALID = 0,
+  DBUS_VALID = 0, /**< the data is valid */
   DBUS_INVALID_UNKNOWN_TYPECODE = 1,
   DBUS_INVALID_MISSING_ARRAY_ELEMENT_TYPE = 2,
   DBUS_INVALID_SIGNATURE_TOO_LONG = 3, /* this one is impossible right now since
@@ -67,7 +73,7 @@ typedef enum
   DBUS_INVALID_ALIGNMENT_PADDING_NOT_NUL = 9,
   DBUS_INVALID_BOOLEAN_NOT_ZERO_OR_ONE = 10,
   DBUS_INVALID_NOT_ENOUGH_DATA = 11,
-  DBUS_INVALID_TOO_MUCH_DATA = 12,
+  DBUS_INVALID_TOO_MUCH_DATA = 12, /**< trailing junk makes it invalid */
   DBUS_INVALID_BAD_BYTE_ORDER = 13,
   DBUS_INVALID_BAD_PROTOCOL_VERSION = 14,
   DBUS_INVALID_BAD_MESSAGE_TYPE = 15,
@@ -184,4 +190,6 @@ DECLARE_DBUS_NAME_CHECK(error_name);
 DECLARE_DBUS_NAME_CHECK(bus_name);
 DECLARE_DBUS_NAME_CHECK(signature);
 
+/** @} */
+
 #endif /* DBUS_MARSHAL_VALIDATE_H */
diff --git a/dbus/dbus-memory.h b/dbus/dbus-memory.h
index 7f6c275d..2c9e19ee 100644
--- a/dbus/dbus-memory.h
+++ b/dbus/dbus-memory.h
@@ -32,6 +32,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusMemory
+ * @{
+ */
+
 void* dbus_malloc        (size_t bytes);
 void* dbus_malloc0       (size_t bytes);
 void* dbus_realloc       (void  *memory,
@@ -47,6 +52,8 @@ typedef void (* DBusFreeFunction) (void *memory);
 
 void dbus_shutdown (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_MEMORY_H */
diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h
index 8be5faa5..16d2272a 100644
--- a/dbus/dbus-message.h
+++ b/dbus/dbus-message.h
@@ -36,11 +36,16 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusMessage
+ * @{
+ */
+
 typedef struct DBusMessage DBusMessage;
 typedef struct DBusMessageIter DBusMessageIter;
 
 /**
- * DBusMessageIter struct; contains no public fields 
+ * DBusMessageIter struct; contains no public fields. 
  */
 struct DBusMessageIter
 { 
@@ -207,6 +212,8 @@ void*       dbus_message_get_data           (DBusMessage      *message,
 int dbus_message_type_from_string (const char *type_str);
 const char * dbus_message_type_to_string (int type);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_MESSAGE_H */
diff --git a/dbus/dbus-pending-call.h b/dbus/dbus-pending-call.h
index ed2de084..ec066178 100644
--- a/dbus/dbus-pending-call.h
+++ b/dbus/dbus-pending-call.h
@@ -33,6 +33,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusPendingCall
+ * @{
+ */
+
 DBusPendingCall* dbus_pending_call_ref       (DBusPendingCall               *pending);
 void         dbus_pending_call_unref         (DBusPendingCall               *pending);
 dbus_bool_t  dbus_pending_call_set_notify    (DBusPendingCall               *pending,
@@ -52,6 +57,9 @@ dbus_bool_t dbus_pending_call_set_data           (DBusPendingCall  *pending,
                                                   DBusFreeFunction  free_data_func);
 void*       dbus_pending_call_get_data           (DBusPendingCall  *pending,
                                                   dbus_int32_t      slot);
+
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_PENDING_CALL_H */
diff --git a/dbus/dbus-server.h b/dbus/dbus-server.h
index b5efb364..caea4d70 100644
--- a/dbus/dbus-server.h
+++ b/dbus/dbus-server.h
@@ -34,6 +34,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusServer
+ * @{
+ */
+
 typedef struct DBusServer DBusServer;
 
 typedef void (* DBusNewConnectionFunction) (DBusServer     *server,
@@ -75,6 +80,8 @@ dbus_bool_t dbus_server_set_data           (DBusServer       *server,
 void*       dbus_server_get_data           (DBusServer       *server,
                                             int               slot);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SERVER_H */
diff --git a/dbus/dbus-signature.h b/dbus/dbus-signature.h
index f7dbb60b..b62a5859 100644
--- a/dbus/dbus-signature.h
+++ b/dbus/dbus-signature.h
@@ -34,6 +34,11 @@
 DBUS_BEGIN_DECLS
 
 /**
+ * @addtogroup DBusSignature
+ * @{
+ */
+
+/**
  * DBusSignatureIter struct; contains no public fields 
  */
 typedef struct
@@ -69,6 +74,8 @@ dbus_bool_t     dbus_type_is_basic                   (int            typecode);
 dbus_bool_t     dbus_type_is_container               (int            typecode);
 dbus_bool_t     dbus_type_is_fixed                   (int            typecode);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SIGNATURE_H */
diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c
index bfacb24e..a218ed5d 100644
--- a/dbus/dbus-string.c
+++ b/dbus/dbus-string.c
@@ -36,9 +36,9 @@
 #include "dbus-sysdeps.h"
 
 /**
- * @defgroup DBusString string class
+ * @defgroup DBusString DBusString class
  * @ingroup  DBusInternals
- * @brief DBusString data structure
+ * @brief DBusString data structure for safer string handling
  *
  * Types and functions related to DBusString. DBusString is intended
  * to be a string class that makes it hard to mess up security issues
diff --git a/dbus/dbus-sysdeps-unix.c b/dbus/dbus-sysdeps-unix.c
index c8a349cc..01b712b3 100644
--- a/dbus/dbus-sysdeps-unix.c
+++ b/dbus/dbus-sysdeps-unix.c
@@ -73,11 +73,6 @@
 #define socklen_t int
 #endif
 
-/**
- * @addtogroup DBusInternalsUtils
- * @{
- */
-
 static dbus_bool_t
 _dbus_open_socket (int              *fd,
                    int               domain,
@@ -2506,6 +2501,4 @@ _dbus_read_local_machine_uuid (DBusGUID   *machine_id,
   return _dbus_read_uuid_file (&filename, machine_id, create_if_not_found, error);
 }
 
-/** @} end of sysdeps */
-
 /* tests in dbus-sysdeps-util.c */
diff --git a/dbus/dbus-sysdeps-unix.h b/dbus/dbus-sysdeps-unix.h
index f1fe3b0c..f72493a7 100644
--- a/dbus/dbus-sysdeps-unix.h
+++ b/dbus/dbus-sysdeps-unix.h
@@ -34,6 +34,13 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @defgroup DBusSysdepsUnix UNIX-specific internal API
+ * @ingroup DBusInternals
+ * @brief Internal system-dependent API available on UNIX only
+ * @{
+ */
+
 dbus_bool_t 
 _dbus_close     (int               fd,
                  DBusError        *error);
@@ -64,6 +71,8 @@ int _dbus_listen_unix_socket  (const char     *path,
                                dbus_bool_t     abstract,
                                DBusError      *error);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SYSDEPS_UNIX_H */
diff --git a/dbus/dbus-sysdeps.c b/dbus/dbus-sysdeps.c
index d1a48617..0ad29fe3 100644
--- a/dbus/dbus-sysdeps.c
+++ b/dbus/dbus-sysdeps.c
@@ -50,7 +50,16 @@ _DBUS_DEFINE_GLOBAL_LOCK (win_fds);
 _DBUS_DEFINE_GLOBAL_LOCK (sid_atom_cache);
 
 /**
- * @addtogroup DBusInternalsUtils
+ * @defgroup DBusSysdeps Internal system-dependent API
+ * @ingroup DBusInternals
+ * @brief Internal system-dependent API available on UNIX and Windows
+ *
+ * The system-dependent API has a dual purpose. First, it encapsulates
+ * all usage of operating system APIs for ease of auditing and to
+ * avoid cluttering the rest of the code with bizarre OS quirks and
+ * headers. Second, it abstracts different operating system APIs for
+ * portability.
+ * 
  * @{
  */
 
diff --git a/dbus/dbus-sysdeps.h b/dbus/dbus-sysdeps.h
index 7db23e57..98ea8d1d 100644
--- a/dbus/dbus-sysdeps.h
+++ b/dbus/dbus-sysdeps.h
@@ -41,6 +41,12 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusSysdeps
+ *
+ * @{
+ */
+
 /* The idea of this file is to encapsulate everywhere that we're
  * relying on external libc features, for ease of security
  * auditing. The idea is from vsftpd. This also gives us a chance to
@@ -386,6 +392,8 @@ dbus_bool_t _dbus_read_local_machine_uuid   (DBusGUID         *machine_id,
                                              DBusError        *error);
 
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SYSDEPS_H */
diff --git a/dbus/dbus-threads.h b/dbus/dbus-threads.h
index 5e5a67ef..ff3a371b 100644
--- a/dbus/dbus-threads.h
+++ b/dbus/dbus-threads.h
@@ -32,6 +32,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusThreads
+ * @{
+ */
+
 typedef struct DBusMutex DBusMutex;
 typedef struct DBusCondVar DBusCondVar;
 
@@ -109,6 +114,8 @@ typedef struct
 dbus_bool_t  dbus_threads_init         (const DBusThreadFunctions *functions);
 dbus_bool_t  dbus_threads_init_default (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_THREADS_H */
diff --git a/dbus/dbus-timeout.h b/dbus/dbus-timeout.h
index f2f21549..1ebf891e 100644
--- a/dbus/dbus-timeout.h
+++ b/dbus/dbus-timeout.h
@@ -28,10 +28,15 @@
 
 DBUS_BEGIN_DECLS
 
-typedef struct DBusTimeoutList DBusTimeoutList;
+/**
+ * @addtogroup DBusTimeoutInternals
+ * @{
+ */
 
 /* Public methods on DBusTimeout are in dbus-connection.h */
 
+typedef struct DBusTimeoutList DBusTimeoutList;
+
 typedef dbus_bool_t (* DBusTimeoutHandler) (void *data);
 
 DBusTimeout* _dbus_timeout_new          (int                 interval,
@@ -62,6 +67,8 @@ void             _dbus_timeout_list_toggle_timeout (DBusTimeoutList           *t
                                                     dbus_bool_t                enabled);
 
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_TIMEOUT_H */
diff --git a/dbus/dbus-types.h b/dbus/dbus-types.h
index 81943dfd..c13f342d 100644
--- a/dbus/dbus-types.h
+++ b/dbus/dbus-types.h
@@ -103,6 +103,22 @@ typedef dbus_uint32_t  dbus_bool_t;
  */
 
 /**
+ * @def DBUS_HAVE_INT64
+ *
+ * Defined if 64-bit integers are available. Will be defined
+ * on any platform you care about, unless you care about
+ * some truly ancient UNIX, or some bizarre embedded platform.
+ *
+ * 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 should feel comfortable ignoring this macro and just using
+ * int64 unconditionally.
+ * 
+ */
+
+/**
  * @def DBUS_INT64_CONSTANT
  *
  * Declare a 64-bit signed integer constant. The macro
diff --git a/dbus/dbus-watch.h b/dbus/dbus-watch.h
index 3dc0b24e..cbb5945c 100644
--- a/dbus/dbus-watch.h
+++ b/dbus/dbus-watch.h
@@ -28,6 +28,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusWatchInternals
+ * @{
+ */
+
 /* Public methods on DBusWatch are in dbus-connection.h */
 
 typedef struct DBusWatchList DBusWatchList;
@@ -69,6 +74,7 @@ void           _dbus_watch_list_toggle_watch  (DBusWatchList           *watch_li
                                                DBusWatch               *watch,
                                                dbus_bool_t              enabled);
 
+/** @} */
 
 DBUS_END_DECLS