2003-02-19 Havoc Pennington <hp@pobox.com>

Throughout: mop up all the Doxygen warnings and undocumented
	stuff.

	* dbus/dbus-sysdeps.c (do_exec): do not use execvp, we don't want
	to search any paths.

	* dbus/dbus-threads.c: move global mutex initializers to
	dbus-internals.h, multiple prototypes was confusing doxygen
	besides being kind of ugly

	* Doxyfile (PREDEFINED): have Doxygen define
	DOXYGEN_SHOULD_SKIP_THIS so we can exclude things from
	docs with #ifndef DOXYGEN_SHOULD_SKIP_THIS
	(do not abuse the feature! it's for stuff like the autogenerated
	macros in dbus-md5.c, not just for things you don't feel like
	documenting...)

ChangeLog

@@ -1,3 +1,22 @@
+2003-02-19  Havoc Pennington  <hp@pobox.com>
+
+	Throughout: mop up all the Doxygen warnings and undocumented
+	stuff.
+	
+	* dbus/dbus-sysdeps.c (do_exec): do not use execvp, we don't want
+	to search any paths.
+
+	* dbus/dbus-threads.c: move global mutex initializers to
+	dbus-internals.h, multiple prototypes was confusing doxygen
+	besides being kind of ugly
+
+	* Doxyfile (PREDEFINED): have Doxygen define
+	DOXYGEN_SHOULD_SKIP_THIS so we can exclude things from 
+	docs with #ifndef DOXYGEN_SHOULD_SKIP_THIS
+	(do not abuse the feature! it's for stuff like the autogenerated 
+	macros in dbus-md5.c, not just for things you don't feel like 
+	documenting...)
+
 2003-02-18  Havoc Pennington  <hp@pobox.com>
 
 	* dbus/dbus-string.c (_dbus_string_zero): new function

dbus/dbus-auth-script.c

@@ -170,6 +170,16 @@ auth_state_to_string (DBusAuthState state)
   return "unknown";
 }
 
+/**
+ * Runs an "auth script" which is a script for testing the
+ * authentication protocol. Scripts send and receive data, and then
+ * include assertions about the state of both ends of the connection
+ * after processing the data. A script succeeds if these assertions
+ * hold.
+ *
+ * @param filename the file containing the script to run
+ * @returns #TRUE if the script succeeds, #FALSE otherwise
+ */
 dbus_bool_t
 _dbus_auth_script_run (const DBusString *filename)
 {

dbus/dbus-connection.c

@@ -82,21 +82,19 @@ struct DBusConnection
 {
   int refcount; /**< Reference count. */
 
-  DBusMutex *mutex;
+  DBusMutex *mutex; /**< Lock on the entire DBusConnection */
 
-  /* Protects dispatch_message */
-  dbus_bool_t dispatch_acquired;
-  DBusCondVar *dispatch_cond;
-  
-  /* Protects transport io path */
-  dbus_bool_t io_path_acquired;
-  DBusCondVar *io_path_cond;
+  dbus_bool_t dispatch_acquired; /**< Protects dispatch_message */
+  DBusCondVar *dispatch_cond;    /**< Protects dispatch_message */
+
+  dbus_bool_t io_path_acquired;  /**< Protects transport io path */
+  DBusCondVar *io_path_cond;     /**< Protects transport io path */
   
   DBusList *outgoing_messages; /**< Queue of messages we need to send, send the end of the list first. */
   DBusList *incoming_messages; /**< Queue of messages we have received, end of the list received most recently. */
 
   DBusMessage *message_borrowed; /**< True if the first incoming message has been borrowed */
-  DBusCondVar *message_returned_cond;
+  DBusCondVar *message_returned_cond; /**< Used with dbus_connection_borrow_message() */
   
   int n_outgoing;              /**< Length of outgoing queue. */
   int n_incoming;              /**< Length of incoming queue. */
@@ -114,7 +112,7 @@ struct DBusConnection
   DBusCounter *connection_counter; /**< Counter that we decrement when finalized */
   
   int client_serial;            /**< Client serial. Increments each time a message is sent  */
-  DBusList *disconnect_message_link;
+  DBusList *disconnect_message_link; /**< Preallocated list node for queueing the disconnection message */
 };
 
 typedef struct
@@ -1955,7 +1953,12 @@ static int  n_allocated_slots = 0;
 static int  n_used_slots = 0;
 static DBusMutex *allocated_slots_lock = NULL;
 
-DBusMutex *_dbus_allocated_slots_init_lock (void);
+/**
+ * Initialize the mutex used for #DBusConnecton data
+ * slot reservations.
+ *
+ * @returns the mutex
+ */
 DBusMutex *
 _dbus_allocated_slots_init_lock (void)
 {

dbus/dbus-internals.h

@@ -33,6 +33,7 @@
 #include <dbus/dbus-types.h>
 #include <dbus/dbus-errors.h>
 #include <dbus/dbus-sysdeps.h>
+#include <dbus/dbus-threads.h>
 
 DBUS_BEGIN_DECLS;
 
@@ -153,6 +154,12 @@ dbus_bool_t _dbus_decrement_fail_alloc_counter (void);
 #define _dbus_decrement_fail_alloc_counter() FALSE
 #endif /* !DBUS_BUILD_TESTS */
 
+/* Thread initializers */
+DBusMutex *_dbus_list_init_lock            (void);
+DBusMutex *_dbus_allocated_slots_init_lock (void);
+DBusMutex *_dbus_atomic_init_lock          (void);
+DBusMutex *_dbus_message_handler_init_lock (void);
+
 DBUS_END_DECLS;
 
 #endif /* DBUS_INTERNALS_H */

dbus/dbus-keyring.c

@@ -77,8 +77,8 @@ typedef struct
  */
 struct DBusKeyring
 {
-  DBusString filename;
-  DBusString lock_filename;
+  DBusString filename;      /**< File containing keyring */
+  DBusString lock_filename; /**< Lock file for changing keyring */
   
   
 };

dbus/dbus-list.c

@@ -37,7 +37,11 @@
 static DBusMemPool *list_pool;
 static DBusMutex *list_pool_lock = NULL;
 
-DBusMutex *_dbus_list_init_lock (void);
+/**
+ * Initializes the global mutex used for allocating list nodes.
+ *
+ * @returns the mutex
+ */
 DBusMutex *
 _dbus_list_init_lock (void)
 {

dbus/dbus-md5.c

@@ -59,13 +59,13 @@
  *
  * @{
  */
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 /*
  * For reference, here is the program that computed the T values.
  */
 #ifdef COMPUTE_T_VALUES
 #include <math.h>
-/* static main is a hack so doxygen won't pick it up */
-static int
+int
 main(int argc, char **argv)
 {
   int i;
@@ -157,6 +157,7 @@ main(int argc, char **argv)
 #define T62 /* 0xbd3af235 */ (T_MASK ^ 0x42c50dca)
 #define T63    0x2ad7d2bb
 #define T64 /* 0xeb86d391 */ (T_MASK ^ 0x14792c6e)
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
 static void
 md5_process(DBusMD5Context *context, const unsigned char *data /*[64]*/)

dbus/dbus-message-handler.c

@@ -38,7 +38,13 @@
  */
 
 static DBusMutex *message_handler_lock = NULL;
-DBusMutex *_dbus_message_handler_init_lock (void);
+
+/**
+ * Initializes the mutex used for threadsafe access to
+ * #DBusMessageHandler objects.
+ *
+ * @returns the mutex
+ */
 DBusMutex *
 _dbus_message_handler_init_lock (void)
 {

dbus/dbus-message.c

@@ -1001,7 +1001,7 @@ dbus_message_get_service (DBusMessage *message)
  * with 0.
  *
  * @param message the message
- * @param first_argument_type type of the first argument
+ * @param first_arg_type type of the first argument
  * @param ... value of first argument, list of additional type-value pairs
  * @returns #TRUE on success
  */
@@ -1735,12 +1735,27 @@ dbus_message_get_sender (DBusMessage *message)
   return get_string_field (message, FIELD_SENDER, NULL);
 }
 
+/**
+ * Checks whether the message has the given name.
+ * If the message has no name or has a different
+ * name, returns #FALSE.
+ *
+ * @param message the message
+ * @param name the name to check (must not be #NULL)
+ * 
+ * @returns #TRUE if the message has the given name
+ */
 dbus_bool_t
 dbus_message_name_is (DBusMessage *message,
 		      const char  *name)
 {
-  if (dbus_message_get_name (message) &&
-      strcmp (dbus_message_get_name (message), name) == 0)
+  const char *n;
+
+  _dbus_assert (name != NULL);
+  
+  n = dbus_message_get_name (message);
+
+  if (n && strcmp (n, name) == 0)
     return TRUE;
   else
     return FALSE;

dbus/dbus-string.c

@@ -2166,7 +2166,7 @@ _dbus_string_validate_nul (const DBusString *str,
 /**
  * Clears all allocated bytes in the string to zero.
  *
- * @param the string
+ * @param str the string
  */
 void
 _dbus_string_zero (DBusString *str)

dbus/dbus-sysdeps.c

@@ -790,6 +790,13 @@ _dbus_string_parse_double (const DBusString *str,
   return TRUE;
 }
 
+/** @} */ /* DBusString group */
+
+/**
+ * @addtogroup DBusInternalsUtils
+ * @{
+ */
+
 /**
  * Gets the credentials corresponding to the given username.
  *
@@ -956,7 +963,12 @@ _dbus_string_append_our_uid (DBusString *str)
 
 
 static DBusMutex *atomic_lock = NULL;
-DBusMutex *_dbus_atomic_init_lock (void);
+/**
+ * Initializes the global mutex for the fallback implementation
+ * of atomic integers.
+ *
+ * @returns the mutex
+ */
 DBusMutex *
 _dbus_atomic_init_lock (void)
 {
@@ -1512,10 +1524,22 @@ _dbus_generate_random_bytes (DBusString *str,
   return FALSE;
 }
 
+/**
+ * A wrapper around strerror()
+ *
+ * @param errnum the errno
+ * @returns an error message (never #NULL)
+ */
 const char *
 _dbus_errno_to_string (int errnum)
 {
-  return strerror (errnum);
+  const char *msg;
+  
+  msg = strerror (errnum);
+  if (msg == NULL)
+    msg = "unknown";
+
+  return msg;
 }
 
 /* Avoids a danger in threaded situations (calling close()
@@ -1636,9 +1660,9 @@ do_exec (int                       child_err_report_fd,
 
   if (child_setup)
     (* child_setup) (user_data);
+
 #ifdef DBUS_BUILD_TESTS
   max_open = sysconf (_SC_OPEN_MAX);
-
   
   for (i = 3; i < max_open; i++)
     {
@@ -1651,7 +1675,7 @@ do_exec (int                       child_err_report_fd,
     }
 #endif
   
-  execvp (argv[0], argv);
+  execv (argv[0], argv);
 
   /* Exec failed */
   write_err_and_exit (child_err_report_fd,
@@ -1659,6 +1683,21 @@ do_exec (int                       child_err_report_fd,
   
 }
 
+/**
+ * Spawns a new process. The executable name and argv[0]
+ * are the same, both are provided in argv[0]. The child_setup
+ * function is passed the given user_data and is run in the child
+ * just before calling exec().
+ *
+ * @todo this code should be reviewed/double-checked as it's fairly
+ * complex and no one has reviewed it yet.
+ *
+ * @param argv the executable and arguments
+ * @param child_setup function to call in child pre-exec()
+ * @param user_data user data for setup function
+ * @param error error object to be filled in if function fails
+ * @returns #TRUE on success, #FALSE if error is filled in
+ */
 dbus_bool_t
 _dbus_spawn_async (char                    **argv,
 		   DBusSpawnChildSetupFunc   child_setup,
@@ -1805,6 +1844,13 @@ _dbus_disable_sigpipe (void)
   signal (SIGPIPE, SIG_IGN);
 }
 
+/**
+ * Sets the file descriptor to be close
+ * on exec. Should be called for all file
+ * descriptors in D-BUS code.
+ *
+ * @param fd the file descriptor
+ */
 void
 _dbus_fd_set_close_on_exec (int fd)
 {

dbus/dbus-threads.c

@@ -154,6 +154,8 @@ dbus_condvar_wait (DBusCondVar *cond,
  * mutex again before returning.
  * Does nothing if passed a #NULL pointer.
  *
+ * @param cond the condition variable
+ * @param mutex the mutex
  * @param timeout_milliseconds the maximum time to wait
  * @returns TRUE if the condition was reached, or FALSE if the
  * timeout was reached.
@@ -193,12 +195,6 @@ dbus_condvar_wake_all (DBusCondVar *cond)
     (* thread_functions.condvar_wake_all) (cond);
 }
 
-
-DBusMutex * _dbus_list_init_lock (void);
-DBusMutex * _dbus_allocated_slots_init_lock (void);
-DBusMutex *_dbus_atomic_init_lock (void);
-DBusMutex *_dbus_message_handler_init_lock (void);
-
 static dbus_bool_t
 init_static_locks(void)
 {