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.

diff --git a/ChangeLog b/ChangeLog
index 5b0c320d74dd3857aee3323f78b5388d26a8ca5b..dc84b9891dea3c970894628088b88c7e12d63a27 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+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 b82495d077d3d2b0b4225ad0b3041dcae0d2235f..8940be5b7597a61890dc9b0145add4c1a702fe18 100644 (file)
--- 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 b4933af32d9af4a10c4d88f673e4e0c26402190c..2c697abd6566118bbc905f3d9fec2c07782fb8ac 100644 (file)
--- 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 1e78c1f3b8f8dff029ca973bddfed451efdb4001..465cdbf43bcfb8f2b0c1ed58a0b07d4c12fcc47e 100644 (file)
--- 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 2438cb260bbfcd5f29e4dcd4258aafbc4e5e567d..3ea12f0c661c26a2097f6372df648deabe997c9c 100644 (file)
--- 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 4424e8c888e6ba97ba41e7fdf62feac7e7734982..71f2f6a4468b6ea4af6f7108ebc63f667a06f1c4 100644 (file)
--- 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 0074c437b24ef0e6ead759c14a8c5ca5621627d4..3436b6ce3d433a1c786e78f62c1cb9aadec10547 100644 (file)
--- a/dbus/dbus-marshal-validate.h
+++ b/dbus/dbus-marshal-validate.h
@@ -30,6 +30,12 @@
 #error "config.h not included here"
 #endif
 
+/**
+ * @addtogroup DBusMarshal
+ *
+ * @{
+ */
+
 /**
  * This is used rather than a bool for high visibility
  */
@@ -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 7f6c275d456f46edb23b8b7217e9e17795dcdcc9..2c9e19ee16b7e7bcbe7e25a90d38309ba165bab5 100644 (file)
--- 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 8be5faa51b311006931ec8bc427b311757a16775..16d2272a324f597dbf757616cca1ceb768576055 100644 (file)
--- 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 ed2de0842f0dc4839b75a003df90ca373679349c..ec066178c4fb4aa8b57858577528f40c7d972ec1 100644 (file)
--- 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 b5efb364696422a21a2b46097c49c8e1c43f2eb2..caea4d70b2ef0bbd863c09028613c9131bdeca15 100644 (file)
--- 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 f7dbb60bc565c8bef1ee8acbc7a218028e612840..b62a5859b5ebfdb778a424cd2208ef34e0bff248 100644 (file)
--- a/dbus/dbus-signature.h
+++ b/dbus/dbus-signature.h
@@ -33,6 +33,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusSignature
+ * @{
+ */
+
 /**
  * DBusSignatureIter struct; contains no public fields 
  */
@@ -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 bfacb24e1055402598083224bd61b11452c96c85..a218ed5d4427f7c6e39f7d83627dce82f2bb8324 100644 (file)
--- 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 c8a349cc14ad8fbb3b71d06ae9e24ff6ee2b2562..01b712b3818aaaf97819477597e4f36cc9ee31e0 100644 (file)
--- 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 f1fe3b0c99de83018efd0dafe25f043dba70a50e..f72493a76d442da4448a715ddfaa19b35a68d5e8 100644 (file)
--- 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 d1a4861746ba42b78bbc979afaa3c002052ae410..0ad29fe38ca103f8e31f5812ef75474cadcd4218 100644 (file)
--- 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 7db23e5735eb17635ee52af96b1dc7f9c725411f..98ea8d1df94de168c9b0f8d51dafe5e6c075148a 100644 (file)
--- 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 5e5a67efc8c7bb8a95b55d6c76005ada469857cd..ff3a371b2987f7c1bef2d0ef236df84ceabb4120 100644 (file)
--- 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 f2f215496ad11e71cbe07e39b109ae43ce80d424..1ebf891eff04ea090f0f59bc448b526f5f99b41c 100644 (file)
--- 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 81943dfdfc95f06078c8343b77c6580a8396651d..c13f342d3bfa97c0313349c6af3ce318cb020859 100644 (file)
--- a/dbus/dbus-types.h
+++ b/dbus/dbus-types.h
@@ -102,6 +102,22 @@ typedef dbus_uint32_t  dbus_bool_t;
  * You probably want to just assume #DBUS_HAVE_INT64 is always defined.
  */
 
+/**
+ * @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
  *

diff --git a/dbus/dbus-watch.h b/dbus/dbus-watch.h
index 3dc0b24e456bc19b1afe519b25f1e12ea23d3c40..cbb5945c9be3504ba89d27b62b7c6f2b9c08d630 100644 (file)
--- 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