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 5b0c320..dc84b98 100644 (file)
--- 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 b82495d..8940be5 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 b4933af..2c697ab 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 1e78c1f..465cdbf 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 2438cb2..3ea12f0 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 4424e8c..71f2f6a 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 0074c43..3436b6c 100644 (file)
--- 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 7f6c275..2c9e19e 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 8be5faa..16d2272 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 ed2de08..ec06617 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 b5efb36..caea4d7 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 f7dbb60..b62a585 100644 (file)
--- 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 bfacb24..a218ed5 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 c8a349c..01b712b 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 f1fe3b0..f72493a 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 d1a4861..0ad29fe 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 7db23e5..98ea8d1 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 5e5a67e..ff3a371 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 f2f2154..1ebf891 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 81943df..c13f342 100644 (file)
--- 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 3dc0b24..cbb5945 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