dbus/dbus dbus-connection.c, 1.147, 1.148 dbus-hash.h, 1.18, 1.19 dbus-marshal-recursive.c, 1.55, 1.56 dbus-marshal-validate.h, 1.14, 1.15 dbus-pending-call.c, 1.23, 1.24 dbus-protocol.h, 1.49, 1.50 dbus-server.c, 1.53, 1.54 dbus-shared.h, 1.10, 1.11 dbus-signature.c, 1.12, 1.13 dbus-sysdeps.h, 1.62, 1.63 dbus-timeout.h, 1.11, 1.12 dbus-watch.h, 1.9, 1.10

Havoc Pennington hp at kemper.freedesktop.org
Sat Oct 21 16:09:20 PDT 2006


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

Modified Files:
	dbus-connection.c dbus-hash.h dbus-marshal-recursive.c 
	dbus-marshal-validate.h dbus-pending-call.c dbus-protocol.h 
	dbus-server.c dbus-shared.h dbus-signature.c dbus-sysdeps.h 
	dbus-timeout.h dbus-watch.h 
Log Message:
2006-10-21  Havoc Pennington  <hp at redhat.com>

	* Documentation! Whee! Doxygen now 100% silent. If you make it
	angry again, you will be punished.
	


Index: dbus-connection.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.c,v
retrieving revision 1.147
retrieving revision 1.148
diff -u -d -r1.147 -r1.148
--- dbus-connection.c	21 Oct 2006 21:57:31 -0000	1.147
+++ dbus-connection.c	21 Oct 2006 23:09:18 -0000	1.148
@@ -2992,23 +2992,19 @@
 }
 
 /**
- * Queues a message to send, as with dbus_connection_send_message(),
+ * Queues a message to send, as with dbus_connection_send(),
  * but also returns a #DBusPendingCall used to receive a reply to the
  * message. If no reply is received in the given timeout_milliseconds,
  * this function expires the pending reply and generates a synthetic
  * error reply (generated in-process, not by the remote application)
  * indicating that a timeout occurred.
  *
- * A #DBusPendingCall will see a reply message after any filters, but
- * before any object instances or other handlers. A #DBusPendingCall
- * will always see exactly one reply message, unless it's cancelled
- * with dbus_pending_call_cancel().
- * 
- * If a filter filters out the reply before the handler sees it, the
- * reply is immediately timed out and a timeout error reply is
- * generated. If a filter removes the timeout error reply then the
- * #DBusPendingCall will get confused. Filtering the timeout error
- * is thus considered a bug and will print a warning.
+ * A #DBusPendingCall will see a reply message before any filters or
+ * registered object path handlers. See dbus_connection_dispatch() for
+ * details on when handlers are run.
+ *
+ * A #DBusPendingCall will always see exactly one reply message,
+ * unless it's cancelled with dbus_pending_call_cancel().
  * 
  * If #NULL is passed for the pending_return, the #DBusPendingCall
  * will still be generated internally, and used to track
@@ -3019,7 +3015,11 @@
  * is typically the best value for the timeout for this reason, unless
  * you want a very short or very long timeout.  There is no way to
  * avoid a timeout entirely, other than passing INT_MAX for the
- * timeout to postpone it indefinitely.
+ * timeout to mean "very long timeout." libdbus clamps an INT_MAX
+ * timeout down to a few hours timeout though.
+ *
+ * @warning if the connection is disconnected, the #DBusPendingCall
+ * will be set to #NULL, so be careful with this.
  * 
  * @param connection the connection
  * @param message the message to send
@@ -3123,16 +3123,24 @@
  * Sends a message and blocks a certain time period while waiting for
  * a reply.  This function does not reenter the main loop,
  * i.e. messages other than the reply are queued up but not
- * processed. This function is used to do non-reentrant "method
- * calls."
+ * processed. This function is used to invoke method calls on a
+ * remote object.
  * 
  * If a normal reply is received, it is returned, and removed from the
  * incoming message queue. If it is not received, #NULL is returned
  * and the error is set to #DBUS_ERROR_NO_REPLY.  If an error reply is
  * received, it is converted to a #DBusError and returned as an error,
- * then the reply message is deleted. If something else goes wrong,
- * result is set to whatever is appropriate, such as
- * #DBUS_ERROR_NO_MEMORY or #DBUS_ERROR_DISCONNECTED.
+ * then the reply message is deleted and #NULL is returned. If
+ * something else goes wrong, result is set to whatever is
+ * appropriate, such as #DBUS_ERROR_NO_MEMORY or
+ * #DBUS_ERROR_DISCONNECTED.
+ *
+ * @warning While this function blocks the calling thread will not be
+ * processing the incoming message queue. This means you can end up
+ * deadlocked if the application you're talking to needs you to reply
+ * to a method. To solve this, either avoid the situation, block in a
+ * separate thread from the main connection-dispatching thread, or use
+ * dbus_pending_call_set_notify() to avoid blocking.
  *
  * @param connection the connection
  * @param message the message to send
@@ -4076,25 +4084,33 @@
 /**
  * Processes any incoming data.
  *
- * If there are messages in the incoming queue,
- * dbus_connection_dispatch() removes one message from the queue and
- * runs any handlers for it (handlers are added with
- * dbus_connection_add_filter() or
- * dbus_connection_register_object_path() for example).
- *
  * If there's incoming raw data that has not yet been parsed, it is
  * parsed, which may or may not result in adding messages to the
  * incoming queue.
+ *
+ * The incoming data buffer is filled when the connection reads from
+ * its underlying transport (such as a socket).  Reading usually
+ * happens in dbus_watch_handle() or dbus_connection_read_write().
  * 
- * The incoming message queue is filled when the connection
- * reads from its underlying transport (such as a socket).
- * Reading usually happens in dbus_watch_handle() or
- * dbus_connection_read_write().
+ * If there are complete messages in the incoming queue,
+ * dbus_connection_dispatch() removes one message from the queue and
+ * processes it. Processing has three steps.
  *
- * If any data has been read from the underlying transport, but not
- * yet dispatched, the dispatch status will be
- * #DBUS_DISPATCH_DATA_REMAINS. See dbus_connection_get_dispatch_status()
- * for more on dispatch statuses.
+ * First, any method replies are passed to #DBusPendingCall or
+ * dbus_connection_send_with_reply_and_block() in order to
+ * complete the pending method call.
+ * 
+ * Second, any filters registered with dbus_connection_add_filter()
+ * are run. If any filter returns #DBUS_HANDLER_RESULT_HANDLED
+ * then processing stops after that filter.
+ *
+ * Third, if the message is a method call it is forwarded to
+ * any registered object path handlers added with
+ * dbus_connection_register_object_path() or
+ * dbus_connection_register_fallback().
+ *
+ * A single call to dbus_connection_dispatch() will process at most
+ * one message; it will not clear the entire message queue.
  *
  * Be careful about calling dbus_connection_dispatch() from inside a
  * message handler, i.e. calling dbus_connection_dispatch()

Index: dbus-hash.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-hash.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- dbus-hash.h	21 Oct 2006 18:17:02 -0000	1.18
+++ dbus-hash.h	21 Oct 2006 23:09:18 -0000	1.19
@@ -123,6 +123,8 @@
 int            _dbus_hash_table_get_n_entries      (DBusHashTable    *table);
 
 /* Preallocation */
+
+/** A preallocated hash entry */
 typedef struct DBusPreallocatedHash DBusPreallocatedHash;
 
 DBusPreallocatedHash *_dbus_hash_table_preallocate_entry          (DBusHashTable        *table);

Index: dbus-marshal-recursive.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-marshal-recursive.c,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- dbus-marshal-recursive.c	21 Oct 2006 17:08:08 -0000	1.55
+++ dbus-marshal-recursive.c	21 Oct 2006 23:09:18 -0000	1.56
@@ -321,7 +321,7 @@
  * type position is stored in the same variable.
  *
  * @param type_str a type signature (must be valid)
- * @param type_pos an integer position in the type signtaure (in and out)
+ * @param type_pos an integer position in the type signature (in and out)
  */
 void
 _dbus_type_signature_next (const char       *type_str,

Index: dbus-marshal-validate.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-marshal-validate.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- dbus-marshal-validate.h	21 Oct 2006 18:51:30 -0000	1.14
+++ dbus-marshal-validate.h	21 Oct 2006 23:09:18 -0000	1.15
@@ -183,11 +183,17 @@
 }
 #endif /* !DBUS_DISABLE_CHECKS */
 
+/** defines _dbus_check_is_valid_path() */
 DECLARE_DBUS_NAME_CHECK(path);
+/** defines _dbus_check_is_valid_interface() */
 DECLARE_DBUS_NAME_CHECK(interface);
+/** defines _dbus_check_is_valid_member() */
 DECLARE_DBUS_NAME_CHECK(member);
+/** defines _dbus_check_is_valid_error_name() */
 DECLARE_DBUS_NAME_CHECK(error_name);
+/** defines _dbus_check_is_valid_bus_name() */
 DECLARE_DBUS_NAME_CHECK(bus_name);
+/** defines _dbus_check_is_valid_signature() */
 DECLARE_DBUS_NAME_CHECK(signature);
 
 /** @} */

Index: dbus-pending-call.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-pending-call.c,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- dbus-pending-call.c	21 Oct 2006 17:21:45 -0000	1.23
+++ dbus-pending-call.c	21 Oct 2006 23:09:18 -0000	1.24
@@ -615,8 +615,14 @@
  * Cancels the pending call, such that any reply or error received
  * will just be ignored.  Drops the dbus library's internal reference
  * to the #DBusPendingCall so will free the call if nobody else is
- * holding a reference. However you usually get a reference
- * from dbus_connection_send() so probably your app owns a ref also.
+ * holding a reference. However you usually get a reference from
+ * dbus_connection_send_with_reply() so probably your app owns a ref
+ * also.
+ *
+ * Note that canceling a pending call will <em>not</em> simulate a
+ * timed-out call; if a call times out, then a timeout error reply is
+ * received. If you cancel the call, no reply is received unless the
+ * the reply was already received before you canceled.
  * 
  * @param pending the pending call
  */

Index: dbus-protocol.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-protocol.h,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -d -r1.49 -r1.50
--- dbus-protocol.h	21 Oct 2006 21:57:31 -0000	1.49
+++ dbus-protocol.h	21 Oct 2006 23:09:18 -0000	1.50
@@ -50,10 +50,10 @@
 
 
 /* Message byte order */
-#define DBUS_LITTLE_ENDIAN ('l')  /**< LSB first */
-#define DBUS_BIG_ENDIAN    ('B')  /**< MSB first */
+#define DBUS_LITTLE_ENDIAN ('l')  /**< Code marking LSB-first byte order in the wire protocol. */
+#define DBUS_BIG_ENDIAN    ('B')  /**< Code marking MSB-first byte order in the wire protocol. */
 
-/** Protocol version */
+/** Protocol version. */
 #define DBUS_MAJOR_PROTOCOL_VERSION 1
 
 /** Type code that is never equal to a legitimate type code */

Index: dbus-server.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-server.c,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -d -r1.53 -r1.54
--- dbus-server.c	21 Oct 2006 17:21:45 -0000	1.53
+++ dbus-server.c	21 Oct 2006 23:09:18 -0000	1.54
@@ -36,12 +36,11 @@
  * @ingroup  DBus
  * @brief Server that listens for new connections.
  *
- * Types and functions related to DBusServer.
  * A DBusServer represents a server that other applications
  * can connect to. Each connection from another application
- * is represented by a DBusConnection.
+ * is represented by a #DBusConnection.
  *
- * @todo Thread safety hasn't been looked at for #DBusServer
+ * @todo Thread safety hasn't been tested much for #DBusServer
  * @todo Need notification to apps of disconnection, may matter for some transports
  */
 
@@ -518,20 +517,23 @@
 };
 
 /**
- * Listens for new connections on the given address.
- * If there are multiple address entries in the address,
- * tries each one and listens on the first one that
- * works.
+ * Listens for new connections on the given address.  If there are
+ * multiple semicolon-separated address entries in the address, tries
+ * each one and listens on the first one that works.
  * 
  * Returns #NULL and sets error if listening fails for any reason.
  * Otherwise returns a new #DBusServer.
- * dbus_server_set_new_connection_function() and
- * dbus_server_set_watch_functions() should be called
- * immediately to render the server fully functional.
+ * dbus_server_set_new_connection_function(),
+ * dbus_server_set_watch_functions(), and
+ * dbus_server_set_timeout_functions() should be called immediately to
+ * render the server fully functional.
+ *
+ * To free the server, applications must call first
+ * dbus_server_disconnect() and then dbus_server_unref().
  * 
  * @param address the address of this server.
- * @param error location to store rationale for failure.
- * @returns a new DBusServer, or #NULL on failure.
+ * @param error location to store reason for failure.
+ * @returns a new #DBusServer, or #NULL on failure.
  * 
  */
 DBusServer*
@@ -841,7 +843,7 @@
 }
 
 /**
- * Sets the watch functions for the connection. These functions are
+ * Sets the watch functions for the server. These functions are
  * responsible for making the application's main loop aware of file
  * descriptors that need to be monitored for events.
  *
@@ -895,7 +897,7 @@
 }
 
 /**
- * Sets the timeout functions for the connection. These functions are
+ * Sets the timeout functions for the server. These functions are
  * responsible for making the application's main loop aware of timeouts.
  *
  * This function behaves exactly like dbus_connection_set_timeout_functions();
@@ -948,10 +950,13 @@
 }
 
 /**
- * Sets the authentication mechanisms that this server offers
- * to clients, as a list of SASL mechanisms. This function
- * only affects connections created *after* it is called.
- * Pass #NULL instead of an array to use all available mechanisms.
+ * Sets the authentication mechanisms that this server offers to
+ * clients, as a #NULL-terminated array of mechanism names. This
+ * function only affects connections created <em>after</em> it is
+ * called.  Pass #NULL instead of an array to use all available
+ * mechanisms (this is the default behavior).
+ *
+ * The D-Bus specification describes some of the supported mechanisms.
  *
  * @param server the server
  * @param mechanisms #NULL-terminated array of mechanisms

Index: dbus-shared.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-shared.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- dbus-shared.h	21 Oct 2006 21:57:31 -0000	1.10
+++ dbus-shared.h	21 Oct 2006 23:09:18 -0000	1.11
@@ -116,8 +116,8 @@
 #define DBUS_RELEASE_NAME_REPLY_NOT_OWNER       3 /**< Service is not an owner of the given name */
 
 /* Replies to service starts */
-#define DBUS_START_REPLY_SUCCESS         1 /**< service was auto started */
-#define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< service was already running */
+#define DBUS_START_REPLY_SUCCESS         1 /**< Service was auto started */
+#define DBUS_START_REPLY_ALREADY_RUNNING 2 /**< Service was already running */
 
 /** @} */
 

Index: dbus-signature.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-signature.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- dbus-signature.c	21 Oct 2006 17:21:45 -0000	1.12
+++ dbus-signature.c	21 Oct 2006 23:09:18 -0000	1.13
@@ -37,6 +37,14 @@
   unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
 } DBusSignatureRealIter;
 
+/** macro that checks whether a typecode is a container type */
+#define TYPE_IS_CONTAINER(typecode)             \
+    ((typecode) == DBUS_TYPE_STRUCT ||          \
+     (typecode) == DBUS_TYPE_DICT_ENTRY ||      \
+     (typecode) == DBUS_TYPE_VARIANT ||         \
+     (typecode) == DBUS_TYPE_ARRAY)
+
+
 /**
  * @defgroup DBusSignature Type signature parsing
  * @ingroup  DBus
@@ -73,10 +81,10 @@
  * character such as '(' for a structure, the corresponding type for
  * the container will be returned, e.g.  DBUS_TYPE_STRUCT, not '('.
  * In this case, you should initialize a sub-iterator with
- * dbus_signature_iter_recurse to parse the container type.
+ * dbus_signature_iter_recurse() to parse the container type.
  *
  * @param iter pointer to an iterator 
- * @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY)
+ * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY)
  */
 int
 dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
@@ -87,11 +95,16 @@
 }
 
 /**
- * Returns the full type signature represented by the current
- * iterator as a C string.
+ * Returns the signature of the single complete type starting at the
+ * given iterator.
+ *
+ * For example, if the iterator is pointing at the start of "(ii)ii"
+ * (which is "a struct of two ints, followed by an int, followed by an
+ * int"), then "(ii)" would be returned. If the iterator is pointing at
+ * one of the "i" then just that "i" would be returned.
  *
  * @param iter pointer to an iterator 
- * @returns current signature; or NULL on OOM.  Should be freed with #dbus_free
+ * @returns current signature; or #NULL if no memory.  Should be freed with dbus_free()
  */
 char *
 dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
@@ -121,8 +134,8 @@
  * This function allows you to avoid initializing a sub-iterator and
  * getting its current type.
  *
- * It is an error to invoke this function if the current type of the
- * iterator is not DBUS_TYPE_ARRAY.
+ * Undefined behavior results if you invoke this function when the
+ * current type of the iterator is not #DBUS_TYPE_ARRAY.
  *
  * @param iter pointer to an iterator 
  * @returns current array element type
@@ -139,7 +152,7 @@
 
 /**
  * Skip to the next value on this "level". e.g. the next field in a
- * struct, the next value in an array. Returns FALSE at the end of the
+ * struct, the next value in an array. Returns #FALSE at the end of the
  * current container.
  *
  * @param iter the iterator
@@ -178,9 +191,12 @@
 }
 
 /**
- * Initialize a new iterator pointing to the first type current
- * container. It's an error to call this if the current type is a
- * non-container (i.e. if dbus_type_is_container returns FALSE).
+ * Initialize a new iterator pointing to the first type in the current
+ * container.
+ * 
+ * The results are undefined when calling this if the current type is
+ * a non-container (i.e. if dbus_type_is_container() returns #FALSE
+ * for the result of dbus_signature_iter_get_current_type()).
  *
  * @param iter the current interator
  * @param subiter an iterator to initialize pointing to the first child
@@ -203,11 +219,13 @@
 }
 
 /**
- * Check a type signature for validity.
+ * Check a type signature for validity. Remember that #NULL can always
+ * be passed instead of a DBusError*, if you don't care about having
+ * an error name and message.
  *
  * @param signature a potentially invalid type signature
  * @param error error return
- * @returns TRUE iif signature is valid
+ * @returns #TRUE if signature is valid or #FALSE if an error is set
  */
 dbus_bool_t
 dbus_signature_validate (const char       *signature,
@@ -224,12 +242,15 @@
 }
 
 /**
- * Check that a type signature is both valid and contains exactly
- * one complete type.
+ * Check that a type signature is both valid and contains exactly one
+ * complete type. "One complete type" means a single basic type,
+ * array, struct, or dictionary, though the struct or array may be
+ * arbitrarily recursive and complex. More than one complete type
+ * would mean for example "ii" or two integers in sequence.
  *
  * @param signature a potentially invalid type signature
  * @param error error return
- * @returns TRUE iif signature is valid and has exactly one complete type
+ * @returns #TRUE if signature is valid and has exactly one complete type
  */
 dbus_bool_t
 dbus_signature_validate_single (const char       *signature,
@@ -250,16 +271,10 @@
   return FALSE;
 }
 
-/** macro that checks whether a typecode is a container type */
-#define TYPE_IS_CONTAINER(typecode)             \
-    ((typecode) == DBUS_TYPE_STRUCT ||          \
-     (typecode) == DBUS_TYPE_DICT_ENTRY ||      \
-     (typecode) == DBUS_TYPE_VARIANT ||         \
-     (typecode) == DBUS_TYPE_ARRAY)
-
 /**
  * A "container type" can contain basic types, or nested
  * container types. #DBUS_TYPE_INVALID is not a container type.
+ *
  * This function will crash if passed a typecode that isn't
  * in dbus-protocol.h
  *
@@ -275,15 +290,15 @@
 }
 
 /**
- * A "basic type" is a somewhat arbitrary concept, but the intent
- * is to include those types that are fully-specified by a single
- * typecode, with no additional type information or nested
- * values. So all numbers and strings are basic types and
- * structs, arrays, and variants are not basic types.
- * #DBUS_TYPE_INVALID is not a basic type.
+ * A "basic type" is a somewhat arbitrary concept, but the intent is
+ * to include those types that are fully-specified by a single
+ * typecode, with no additional type information or nested values. So
+ * all numbers and strings are basic types and structs, arrays, and
+ * variants are not basic types.  #DBUS_TYPE_INVALID is not a basic
+ * type.
  *
  * This function will crash if passed a typecode that isn't
- * in dbus-protocol.h
+ * in dbus-protocol.h 
  *
  * @returns #TRUE if type is basic
  */
@@ -304,14 +319,25 @@
  * first byte of the old and new value would be in the same location,
  * so alignment padding is not a factor.
  *
- * This function is useful to determine whether #dbus_message_iter_get_fixed_array
- * may be used.
+ * This function is useful to determine whether
+ * dbus_message_iter_get_fixed_array() may be used.
  *
+ * Some structs are fixed-size (if they contain only fixed-size types)
+ * but struct is not considered a fixed type for purposes of this
+ * function.
+ *
+ * This function will crash if passed a typecode that isn't
+ * in dbus-protocol.h
+ * 
  * @returns #FALSE if the type can occupy different lengths
  */
 dbus_bool_t
 dbus_type_is_fixed (int typecode)
 {
+  /* only reasonable (non-line-noise) typecodes are allowed */
+  _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
+			    FALSE);
+  
   switch (typecode)
     {
     case DBUS_TYPE_BYTE:

Index: dbus-sysdeps.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-sysdeps.h,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -d -r1.62 -r1.63
--- dbus-sysdeps.h	21 Oct 2006 18:17:02 -0000	1.62
+++ dbus-sysdeps.h	21 Oct 2006 23:09:18 -0000	1.63
@@ -56,41 +56,51 @@
  * dbus-memory.c)
  */
 
+/** An opaque string type */
 typedef struct DBusString DBusString;
 
 #if     __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
 #define _DBUS_GNUC_PRINTF( format_idx, arg_idx )    \
   __attribute__((__format__ (__printf__, format_idx, arg_idx)))
-#define _DBUS_GNUC_SCANF( format_idx, arg_idx )     \
-  __attribute__((__format__ (__scanf__, format_idx, arg_idx)))
-#define _DBUS_GNUC_FORMAT( arg_idx )                \
-  __attribute__((__format_arg__ (arg_idx)))
 #define _DBUS_GNUC_NORETURN                         \
   __attribute__((__noreturn__))
 #else   /* !__GNUC__ */
 #define _DBUS_GNUC_PRINTF( format_idx, arg_idx )
-#define _DBUS_GNUC_SCANF( format_idx, arg_idx )
-#define _DBUS_GNUC_FORMAT( arg_idx )
 #define _DBUS_GNUC_NORETURN
 #endif  /* !__GNUC__ */
 
+/** @def _DBUS_GNUC_PRINTF
+ * used to tell gcc about printf format strings
+ */
+/** @def _DBUS_GNUC_NORETURN
+ * used to tell gcc about functions that never return, such as _dbus_abort()
+ */
+
 void _dbus_abort (void) _DBUS_GNUC_NORETURN;
 
 const char* _dbus_getenv (const char *varname);
 dbus_bool_t _dbus_setenv (const char *varname,
 			  const char *value);
 
-
+/** A process ID */
 typedef unsigned long dbus_pid_t;
+/** A user ID */
 typedef unsigned long dbus_uid_t;
+/** A group ID */
 typedef unsigned long dbus_gid_t;
 
+/** an invalid PID used to represent an uninitialized dbus_pid_t field */
 #define DBUS_PID_UNSET ((dbus_pid_t) -1)
+/** an invalid UID used to represent an uninitialized dbus_uid_t field */
 #define DBUS_UID_UNSET ((dbus_uid_t) -1)
+/** an invalid GID used to represent an uninitialized dbus_gid_t field */
 #define DBUS_GID_UNSET ((dbus_gid_t) -1)
 
+/** an appropriate printf format for dbus_pid_t */
 #define DBUS_PID_FORMAT "%lu"
+/** an appropriate printf format for dbus_uid_t */
 #define DBUS_UID_FORMAT "%lu"
+/** an appropriate printf format for dbus_gid_t */
 #define DBUS_GID_FORMAT "%lu"
 
 
@@ -156,7 +166,9 @@
                                                     const DBusCredentials *provided_credentials);
 
 
+/** Information about a UNIX user */
 typedef struct DBusUserInfo  DBusUserInfo;
+/** Information about a UNIX group */
 typedef struct DBusGroupInfo DBusGroupInfo;
 
 /**
@@ -202,10 +214,13 @@
 dbus_uid_t    _dbus_getuid (void);
 dbus_gid_t    _dbus_getgid (void);
 
+/** Opaque type representing an atomically-modifiable integer
+ * that can be used from multiple threads.
+ */
 typedef struct DBusAtomic DBusAtomic;
 
 /**
- * An atomic integer.
+ * An atomic integer safe to increment or decrement from multiple threads.
  */
 struct DBusAtomic
 {
@@ -215,12 +230,18 @@
 dbus_int32_t _dbus_atomic_inc (DBusAtomic *atomic);
 dbus_int32_t _dbus_atomic_dec (DBusAtomic *atomic);
 
-#define _DBUS_POLLIN      0x0001    /* There is data to read */
-#define _DBUS_POLLPRI     0x0002    /* There is urgent data to read */
-#define _DBUS_POLLOUT     0x0004    /* Writing now will not block */
-#define _DBUS_POLLERR     0x0008    /* Error condition */
-#define _DBUS_POLLHUP     0x0010    /* Hung up */
-#define _DBUS_POLLNVAL    0x0020    /* Invalid request: fd not open */
+/** There is data to read */
+#define _DBUS_POLLIN      0x0001
+/** There is urgent data to read */
+#define _DBUS_POLLPRI     0x0002
+/** Writing now will not block */
+#define _DBUS_POLLOUT     0x0004
+/** Error condition */
+#define _DBUS_POLLERR     0x0008
+/** Hung up */
+#define _DBUS_POLLHUP     0x0010
+/** Invalid request: fd not open */
+#define _DBUS_POLLNVAL    0x0020
 
 /**
  * A portable struct pollfd wrapper. 
@@ -267,6 +288,7 @@
                                        DBusString       *dirname);
 dbus_bool_t _dbus_path_is_absolute    (const DBusString *filename);
 
+/** Opaque type for reading a directory listing */
 typedef struct DBusDirIter DBusDirIter;
 
 DBusDirIter* _dbus_directory_open          (const DBusString *filename,
@@ -295,7 +317,6 @@
 dbus_bool_t _dbus_generate_random_ascii        (DBusString *str,
                                                 int         n_bytes);
 
-const char *_dbus_errno_to_string  (int errnum);
 const char* _dbus_error_from_errno (int error_number);
 
 void _dbus_disable_sigpipe (void);
@@ -342,6 +363,7 @@
                                    unsigned long     gid,
                                    DBusError        *error);
 
+/** A UNIX signal handler */
 typedef void (* DBusSignalHandler) (int sig);
 
 void _dbus_set_signal_handler (int               sig,
@@ -363,12 +385,18 @@
 #  endif /* va_list is a pointer */
 #endif /* !DBUS_VA_COPY */
 
-/* On x86 there is an 80-bit FPU, and if you do "a == b" it may have a
- * or b in an 80-bit register, thus failing to compare the two 64-bit
- * doubles for bitwise equality.
+
+/**
+ * Casts a primitive C type to a byte array and then indexes
+ * a particular byte of the array.
  */
 #define _DBUS_BYTE_OF_PRIMITIVE(p, i) \
     (((const char*)&(p))[(i)])
+/** On x86 there is an 80-bit FPU, and if you do "a == b" it may have a
+ * or b in an 80-bit register, thus failing to compare the two 64-bit
+ * doubles for bitwise equality. So this macro compares the two doubles
+ * bitwise.
+ */
 #define _DBUS_DOUBLES_BITWISE_EQUAL(a, b)                                       \
      (_DBUS_BYTE_OF_PRIMITIVE (a, 0) == _DBUS_BYTE_OF_PRIMITIVE (b, 0) &&       \
       _DBUS_BYTE_OF_PRIMITIVE (a, 1) == _DBUS_BYTE_OF_PRIMITIVE (b, 1) &&       \
@@ -385,6 +413,9 @@
 dbus_bool_t _dbus_get_autolaunch_address (DBusString *address, 
 					  DBusError *error);
 
+/** Type representing a universally unique ID
+ * @todo rename to UUID instead of GUID
+ */
 typedef union DBusGUID DBusGUID;
 
 dbus_bool_t _dbus_read_local_machine_uuid   (DBusGUID         *machine_id,

Index: dbus-timeout.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-timeout.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- dbus-timeout.h	21 Oct 2006 18:17:02 -0000	1.11
+++ dbus-timeout.h	21 Oct 2006 23:09:18 -0000	1.12
@@ -37,6 +37,7 @@
 
 typedef struct DBusTimeoutList DBusTimeoutList;
 
+/** function to run when the timeout is handled */
 typedef dbus_bool_t (* DBusTimeoutHandler) (void *data);
 
 DBusTimeout* _dbus_timeout_new          (int                 interval,

Index: dbus-watch.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-watch.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- dbus-watch.h	21 Oct 2006 18:17:02 -0000	1.9
+++ dbus-watch.h	21 Oct 2006 23:09:18 -0000	1.10
@@ -37,6 +37,7 @@
 
 typedef struct DBusWatchList DBusWatchList;
 
+/** function to run when the watch is handled */
 typedef dbus_bool_t (* DBusWatchHandler) (DBusWatch    *watch,
                                           unsigned int  flags,
                                           void         *data);



More information about the dbus-commit mailing list