Sat Oct 21 11:17:05 PDT 2006

Update of /cvs/dbus/dbus/dbus
In directory kemper:/tmp/cvs-serv1375/dbus

Modified Files:
	dbus-address.h dbus-bus.h dbus-connection.h dbus-errors.h 
	dbus-hash.h dbus-marshal-validate.h dbus-memory.h 
	dbus-message.h dbus-pending-call.h dbus-server.h 
	dbus-signature.h dbus-string.c dbus-sysdeps-unix.c 
	dbus-sysdeps-unix.h dbus-sysdeps.c dbus-sysdeps.h 
	dbus-threads.h dbus-timeout.h dbus-types.h dbus-watch.h 
Log Message:
2006-10-21  Havoc Pennington  <hp at 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.
	


Index: dbus-address.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-address.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6

--- dbus-address.h	11 Feb 2005 03:37:03 -0000	1.5
+++ dbus-address.h	21 Oct 2006 18:17:02 -0000	1.6
@@ -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_unescape_value (const char *value,
                                    DBusError  *error);
 
+/** @} */
+
+DBUS_END_DECLS
+
 #endif /* DBUS_ADDRESS_H */
 

Index: dbus-bus.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-bus.h,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- dbus-bus.h	1 Oct 2006 15:36:18 -0000	1.19
+++ dbus-bus.h	21 Oct 2006 18:17:02 -0000	1.20
@@ -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_notify_shared_connection_disconnected_unlocked (DBusConnection *connection);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_BUS_H */

Index: dbus-connection.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.h,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -d -r1.44 -r1.45
--- dbus-connection.h	1 Oct 2006 03:18:47 -0000	1.44
+++ dbus-connection.h	21 Oct 2006 18:17:02 -0000	1.45
@@ -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 @@
 
 char*       dbus_get_local_machine_id              (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_CONNECTION_H */

Index: dbus-errors.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-errors.h,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- dbus-errors.h	9 Sep 2004 10:20:17 -0000	1.26
+++ dbus-errors.h	21 Oct 2006 18:17:02 -0000	1.27
@@ -33,6 +33,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusErrors
+ * @{
+ */
+
 typedef struct DBusError DBusError;
 
 /**
@@ -67,6 +72,8 @@
                                   const char      *name);
 dbus_bool_t dbus_error_is_set    (const DBusError *error);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_ERROR_H */

Index: dbus-hash.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-hash.h,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -d -r1.17 -r1.18
--- dbus-hash.h	20 Oct 2006 03:04:59 -0000	1.17
+++ dbus-hash.h	21 Oct 2006 18:17:02 -0000	1.18
@@ -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 @@
                                                                    char                 *key,
                                                                    void                 *value);
 
+/** @} */
 
 DBUS_END_DECLS
 

Index: dbus-marshal-validate.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-marshal-validate.h,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- dbus-marshal-validate.h	15 Jun 2005 15:15:32 -0000	1.12
+++ dbus-marshal-validate.h	21 Oct 2006 18:17:02 -0000	1.13
@@ -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
 {
 #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 @@
   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(bus_name);
 DECLARE_DBUS_NAME_CHECK(signature);
 
+/** @} */
+
 #endif /* DBUS_MARSHAL_VALIDATE_H */

Index: dbus-memory.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-memory.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- dbus-memory.h	3 Aug 2006 20:34:36 -0000	1.11
+++ dbus-memory.h	21 Oct 2006 18:17:02 -0000	1.12
@@ -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 @@
 
 void dbus_shutdown (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_MEMORY_H */

Index: dbus-message.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-message.h,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -d -r1.63 -r1.64
--- dbus-message.h	21 Oct 2006 17:43:30 -0000	1.63
+++ dbus-message.h	21 Oct 2006 18:17:02 -0000	1.64
@@ -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 @@
 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 */

Index: dbus-pending-call.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-pending-call.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- dbus-pending-call.h	12 Jul 2006 15:57:01 -0000	1.8
+++ dbus-pending-call.h	21 Oct 2006 18:17:02 -0000	1.9
@@ -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 @@
                                                   DBusFreeFunction  free_data_func);
 void*       dbus_pending_call_get_data           (DBusPendingCall  *pending,
                                                   dbus_int32_t      slot);
+
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_PENDING_CALL_H */

Index: dbus-server.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-server.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- dbus-server.h	9 Sep 2004 10:20:17 -0000	1.18
+++ dbus-server.h	21 Oct 2006 18:17:02 -0000	1.19
@@ -34,6 +34,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusServer
+ * @{
+ */
+
 typedef struct DBusServer DBusServer;
 
 typedef void (* DBusNewConnectionFunction) (DBusServer     *server,
@@ -75,6 +80,8 @@
 void*       dbus_server_get_data           (DBusServer       *server,
                                             int               slot);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SERVER_H */

Index: dbus-signature.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-signature.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- dbus-signature.h	3 Aug 2006 20:34:36 -0000	1.5
+++ dbus-signature.h	21 Oct 2006 18:17:02 -0000	1.6
@@ -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_container               (int            typecode);
 dbus_bool_t     dbus_type_is_fixed                   (int            typecode);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SIGNATURE_H */

Index: dbus-string.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-string.c,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -d -r1.74 -r1.75
--- dbus-string.c	20 Oct 2006 03:04:59 -0000	1.74
+++ dbus-string.c	21 Oct 2006 18:17:02 -0000	1.75
@@ -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

Index: dbus-sysdeps-unix.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-sysdeps-unix.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- dbus-sysdeps-unix.c	20 Oct 2006 03:04:59 -0000	1.12
+++ dbus-sysdeps-unix.c	21 Oct 2006 18:17:02 -0000	1.13
@@ -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 @@
   return _dbus_read_uuid_file (&filename, machine_id, create_if_not_found, error);
 }
 
-/** @} end of sysdeps */
-
 /* tests in dbus-sysdeps-util.c */

Index: dbus-sysdeps-unix.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-sysdeps-unix.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- dbus-sysdeps-unix.h	16 Sep 2006 17:38:24 -0000	1.2
+++ dbus-sysdeps-unix.h	21 Oct 2006 18:17:02 -0000	1.3
@@ -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 @@
                                dbus_bool_t     abstract,
                                DBusError      *error);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SYSDEPS_UNIX_H */

Index: dbus-sysdeps.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-sysdeps.c,v
retrieving revision 1.117
retrieving revision 1.118
diff -u -d -r1.117 -r1.118
--- dbus-sysdeps.c	2 Oct 2006 18:45:27 -0000	1.117
+++ dbus-sysdeps.c	21 Oct 2006 18:17:02 -0000	1.118
@@ -50,7 +50,16 @@
 _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.
+ * 
  * @{
  */
 

Index: dbus-sysdeps.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-sysdeps.h,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -d -r1.61 -r1.62
--- dbus-sysdeps.h	1 Oct 2006 03:18:47 -0000	1.61
+++ dbus-sysdeps.h	21 Oct 2006 18:17:02 -0000	1.62
@@ -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 @@
                                              DBusError        *error);
 
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_SYSDEPS_H */

Index: dbus-threads.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-threads.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- dbus-threads.h	14 Sep 2006 04:26:00 -0000	1.11
+++ dbus-threads.h	21 Oct 2006 18:17:02 -0000	1.12
@@ -32,6 +32,11 @@
 
 DBUS_BEGIN_DECLS
 
+/**
+ * @addtogroup DBusThreads
+ * @{
+ */
+
 typedef struct DBusMutex DBusMutex;
 typedef struct DBusCondVar DBusCondVar;
 
@@ -109,6 +114,8 @@
 dbus_bool_t  dbus_threads_init         (const DBusThreadFunctions *functions);
 dbus_bool_t  dbus_threads_init_default (void);
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_THREADS_H */

Index: dbus-timeout.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-timeout.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- dbus-timeout.h	9 Sep 2004 10:20:17 -0000	1.10
+++ dbus-timeout.h	21 Oct 2006 18:17:02 -0000	1.11
@@ -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 @@
                                                     dbus_bool_t                enabled);
 
 
+/** @} */
+
 DBUS_END_DECLS
 
 #endif /* DBUS_TIMEOUT_H */

Index: dbus-types.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-types.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- dbus-types.h	20 Oct 2006 03:05:00 -0000	1.14
+++ dbus-types.h	21 Oct 2006 18:17:02 -0000	1.15
@@ -103,6 +103,22 @@
  */
 
 /**
+ * @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

Index: dbus-watch.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-watch.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- dbus-watch.h	9 Sep 2004 10:20:17 -0000	1.8
+++ dbus-watch.h	21 Oct 2006 18:17:02 -0000	1.9
@@ -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 @@
                                                DBusWatch               *watch,
                                                dbus_bool_t              enabled);
 
+/** @} */
 
 DBUS_END_DECLS
 

