2005-01-16 Havoc Pennington <hp@redhat.com>

        * Add and fix docs according to Doxygen warnings throughout
	source.

	* dbus/dbus-marshal-recursive.c
	(_dbus_type_reader_array_is_empty): change this to just call
	array_reader_get_array_len() and make it static

	* dbus/dbus-message.c (dbus_message_iter_get_element_type): rename
	from get_array_type
	(dbus_message_iter_init_append): rename from append_iter_init

	* dbus/dbus-marshal-recursive.c
	(_dbus_type_reader_get_element_type): rename from
	_dbus_type_reader_get_array_type

11 files changed, 261 insertions, 124 deletions

diff --git a/dbus/dbus-marshal-basic.c b/dbus/dbus-marshal-basic.c
index a2e32752..0da10358 100644
--- a/dbus/dbus-marshal-basic.c
+++ b/dbus/dbus-marshal-basic.c
@@ -1173,6 +1173,7 @@ _dbus_type_is_valid (int typecode)
     }
 }
 
+/** macro that checks whether a typecode is a container type */
 #define TYPE_IS_CONTAINER(typecode)             \
     ((typecode) == DBUS_TYPE_STRUCT ||          \
      (typecode) == DBUS_TYPE_VARIANT ||         \
diff --git a/dbus/dbus-marshal-basic.h b/dbus/dbus-marshal-basic.h
index cf86e713..870fc0f7 100644
--- a/dbus/dbus-marshal-basic.h
+++ b/dbus/dbus-marshal-basic.h
@@ -112,28 +112,37 @@
 #define DBUS_UINT64_FROM_BE(val) (DBUS_UINT64_TO_BE (val))
 #endif /* DBUS_HAVE_INT64 */
 
-#ifdef DBUS_HAVE_INT64
+#ifndef DBUS_HAVE_INT64
+/**
+ * An 8-byte struct you could use to access int64 without having
+ * int64 support
+ */
 typedef struct
 {
-  dbus_uint32_t first32;
-  dbus_uint32_t second32;
+  dbus_uint32_t first32;  /**< first 32 bits in the 8 bytes (beware endian issues) */
+  dbus_uint32_t second32; /**< second 32 bits in the 8 bytes (beware endian issues) */
 } DBus8ByteStruct;
 #endif /* DBUS_HAVE_INT64 */
 
+/**
+ * A simple 8-byte value union that lets you access 8 bytes as if they
+ * were various types; useful when dealing with basic types via
+ * void pointers and varargs.
+ */
 typedef union
 {
-  dbus_int32_t  i32;
-  dbus_uint32_t u32;
+  dbus_int32_t  i32;   /**< as int32 */
+  dbus_uint32_t u32;   /**< as int32 */
 #ifdef DBUS_HAVE_INT64
-  dbus_int64_t  i64;
-  dbus_uint64_t u64;
+  dbus_int64_t  i64;   /**< as int32 */
+  dbus_uint64_t u64;   /**< as int32 */
 #else
-  DBus8ByteStruct u64;
+  DBus8ByteStruct u64; /**< as 8-byte-struct */
 #endif
-  double dbl;
-  unsigned char byt;
-  unsigned char boo;
-  char *str;
+  double dbl;          /**< as double */
+  unsigned char byt;   /**< as byte */
+  unsigned char boo;   /**< as boolean */
+  char *str;           /**< as char* */
 } DBusBasicValue;
 
 #ifdef DBUS_DISABLE_ASSERT
diff --git a/dbus/dbus-marshal-header.c b/dbus/dbus-marshal-header.c
index 58ba86fe..a3711155 100644
--- a/dbus/dbus-marshal-header.c
+++ b/dbus/dbus-marshal-header.c
@@ -33,11 +33,16 @@
 
 /* Not thread locked, but strictly const/read-only so should be OK
  */
+/** Static #DBusString containing the signature of a message header */
 _DBUS_STRING_DEFINE_STATIC(_dbus_header_signature_str, DBUS_HEADER_SIGNATURE);
+/** Static #DBusString containing the local interface */
 _DBUS_STRING_DEFINE_STATIC(_dbus_local_interface_str,  DBUS_INTERFACE_ORG_FREEDESKTOP_LOCAL);
+/** Static #DBusString containing the local path */
 _DBUS_STRING_DEFINE_STATIC(_dbus_local_path_str,       DBUS_PATH_ORG_FREEDESKTOP_LOCAL);
 
+/** Offset from start of _dbus_header_signature_str to the signature of the fields array */
 #define FIELDS_ARRAY_SIGNATURE_OFFSET 6
+/** Offset from start of _dbus_header_signature_str to the signature of an element of the fields array */
 #define FIELDS_ARRAY_ELEMENT_SIGNATURE_OFFSET 7
 
 
@@ -77,8 +82,10 @@ _dbus_header_field_types[DBUS_HEADER_FIELD_LAST+1] = {
   { DBUS_HEADER_FIELD_SIGNATURE, DBUS_TYPE_SIGNATURE }
 };
 
+/** Macro to look up the correct type for a field */
 #define EXPECTED_TYPE_OF_FIELD(field) (_dbus_header_field_types[field].type)
 
+/** The most padding we could ever need for a header */
 #define MAX_POSSIBLE_HEADER_PADDING 7
 static dbus_bool_t
 reserve_header_padding (DBusHeader *header)
@@ -108,6 +115,7 @@ correct_header_padding (DBusHeader *header)
   header->padding = _dbus_string_get_length (&header->data) - unpadded_len;
 }
 
+/** Compute the end of the header, ignoring padding */
 #define HEADER_END_BEFORE_PADDING(header) \
   (_dbus_string_get_length (&(header)->data) - (header)->padding)
 
@@ -635,6 +643,7 @@ _dbus_header_create (DBusHeader  *header,
  * contain the entire message (assuming the claimed lengths are
  * accurate). Also checks that the lengths are in sanity parameters.
  *
+ * @param max_message_length maximum length of a valid message
  * @param validity return location for why the data is invalid if it is
  * @param byte_order return location for byte order
  * @param fields_array_len return location for claimed fields array length
diff --git a/dbus/dbus-marshal-header.h b/dbus/dbus-marshal-header.h
index 32bf51eb..61e9246a 100644
--- a/dbus/dbus-marshal-header.h
+++ b/dbus/dbus-marshal-header.h
@@ -46,6 +46,9 @@ struct DBusHeaderField
   int            value_pos; /**< Position of field value, or -1/-2 */
 };
 
+/**
+ * Message header data and some cached details of it.
+ */
 struct DBusHeader
 {
   DBusString data; /**< Header network data, stored
diff --git a/dbus/dbus-marshal-recursive.c b/dbus/dbus-marshal-recursive.c
index a8bad46a..2d4338ad 100644
--- a/dbus/dbus-marshal-recursive.c
+++ b/dbus/dbus-marshal-recursive.c
@@ -29,7 +29,11 @@
  * @addtogroup DBusMarshal
  * @{
  */
+
+/** turn this on to get deluged in TypeReader verbose spam */
 #define RECURSIVE_MARSHAL_READ_TRACE  0
+
+/** turn this on to get deluged in TypeWriter verbose spam */
 #define RECURSIVE_MARSHAL_WRITE_TRACE 0
 
 static void
@@ -101,18 +105,21 @@ apply_and_free_fixups (DBusList      **fixups,
   *fixups = NULL;
 }
 
+/**
+ * Virtual table for a type reader.
+ */
 struct DBusTypeReaderClass
 {
-  const char *name;
-  int         id;         /* index in all_reader_classes */
-  dbus_bool_t types_only; /* only iterates over types, not values */
+  const char *name;       /**< name for debugging */
+  int         id;         /**< index in all_reader_classes */
+  dbus_bool_t types_only; /**< only iterates over types, not values */
   void        (* recurse)          (DBusTypeReader        *sub,
-                                    DBusTypeReader        *parent);
-  dbus_bool_t (* check_finished)   (const DBusTypeReader  *reader);
+                                    DBusTypeReader        *parent); /**< recurse with this reader as sub */
+  dbus_bool_t (* check_finished)   (const DBusTypeReader  *reader); /**< check whether reader is at the end */
   void        (* next)             (DBusTypeReader        *reader,
-                                    int                    current_type);
+                                    int                    current_type); /**< go to the next value */
   void        (* init_from_mark)   (DBusTypeReader        *reader,
-                                    const DBusTypeMark    *mark);
+                                    const DBusTypeMark    *mark);  /**< uncompress from a mark */
 };
 
 static int
@@ -201,7 +208,8 @@ array_types_only_reader_recurse (DBusTypeReader *sub,
   sub->array_len_offset = 7;
 }
 
-/* array_len_offset is the offset back from start_pos to end of the len */
+/** compute position of array length given array_len_offset, which is
+    the offset back from start_pos to end of the len */
 #define ARRAY_READER_LEN_POS(reader) \
   ((reader)->u.array.start_pos - ((int)(reader)->array_len_offset) - 4)
 
@@ -216,7 +224,7 @@ array_reader_get_array_len (const DBusTypeReader *reader)
   _dbus_assert (_DBUS_ALIGN_VALUE (len_pos, 4) == (unsigned) len_pos);
   array_len = _dbus_unpack_uint32 (reader->byte_order,
                                    _dbus_string_get_const_data_len (reader->value_str, len_pos, 4));
-  
+
 #if RECURSIVE_MARSHAL_READ_TRACE
   _dbus_verbose ("   reader %p len_pos %d array len %u len_offset %d\n",
                  reader, len_pos, array_len, reader->array_len_offset);
@@ -315,27 +323,27 @@ skip_one_complete_type (const DBusString *type_str,
 {
   const unsigned char *p;
   const unsigned char *start;
-  
+
   start = _dbus_string_get_const_data (type_str);
   p = start + *type_pos;
 
   while (*p == DBUS_TYPE_ARRAY)
     ++p;
-  
+
   if (*p == DBUS_STRUCT_BEGIN_CHAR)
     {
       int depth;
-      
+
       depth = 1;
-      
+
       while (TRUE)
         {
           _dbus_assert (*p != DBUS_TYPE_INVALID);
-          
+
           ++p;
 
           _dbus_assert (*p != DBUS_TYPE_INVALID);
-          
+
           if (*p == DBUS_STRUCT_BEGIN_CHAR)
             depth += 1;
           else if (*p == DBUS_STRUCT_END_CHAR)
@@ -632,6 +640,16 @@ all_reader_classes[] = {
   &variant_reader_class
 };
 
+/**
+ * Initializes a type reader.
+ *
+ * @param reader the reader
+ * @param byte_order the byte order of the block to read
+ * @param type_str the signature of the block to read
+ * @param type_pos location of signature
+ * @param value_str the string containing values block
+ * @param value_pos start of values block
+ */
 void
 _dbus_type_reader_init (DBusTypeReader    *reader,
                         int                byte_order,
@@ -652,6 +670,17 @@ _dbus_type_reader_init (DBusTypeReader    *reader,
 #endif
 }
 
+/**
+ * Initializes a type reader that's been compressed into a
+ * DBusTypeMark.  The args have to be the same as those passed in to
+ * create the original #DBusTypeReader.
+ *
+ * @param reader the reader
+ * @param byte_order the byte order of the value block
+ * @param type_str string containing the type signature
+ * @param value_str string containing the values block
+ * @param mark the mark to decompress from
+ */
 void
 _dbus_type_reader_init_from_mark (DBusTypeReader     *reader,
                                   int                 byte_order,
@@ -676,6 +705,14 @@ _dbus_type_reader_init_from_mark (DBusTypeReader     *reader,
 #endif
 }
 
+/**
+ * Like _dbus_type_reader_init() but the iteration is over the
+ * signature, not over values.
+ *
+ * @param reader the reader
+ * @param type_str the signature string
+ * @param type_pos location in the signature string
+ */
 void
 _dbus_type_reader_init_types_only (DBusTypeReader    *reader,
                                    const DBusString  *type_str,
@@ -693,6 +730,14 @@ _dbus_type_reader_init_types_only (DBusTypeReader    *reader,
 #endif
 }
 
+/**
+ * Like _dbus_type_reader_init_from_mark() but only iterates over
+ * the signature, not the values.
+ *
+ * @param reader the reader
+ * @param type_str the signature string
+ * @param mark the mark to decompress from
+ */
 void
 _dbus_type_reader_init_types_only_from_mark (DBusTypeReader     *reader,
                                              const DBusString   *type_str,
@@ -716,6 +761,13 @@ _dbus_type_reader_init_types_only_from_mark (DBusTypeReader     *reader,
 #endif
 }
 
+/**
+ * Compresses a type reader into a #DBusTypeMark, useful for example
+ * if you want to cache a bunch of positions in a block of values.
+ *
+ * @param reader the reader
+ * @param mark the mark to init
+ */
 void
 _dbus_type_reader_save_mark (const DBusTypeReader *reader,
                              DBusTypeMark         *mark)
@@ -732,6 +784,14 @@ _dbus_type_reader_save_mark (const DBusTypeReader *reader,
   mark->array_start_pos = reader->u.array.start_pos;
 }
 
+/**
+ * Gets the type of the value the reader is currently pointing to;
+ * or for a types-only reader gets the type it's currently pointing to.
+ * If the reader is at the end of a block or end of a container such
+ * as an array, returns #DBUS_TYPE_INVALID.
+ *
+ * @param reader the reader
+ */
 int
 _dbus_type_reader_get_current_type (const DBusTypeReader *reader)
 {
@@ -757,8 +817,16 @@ _dbus_type_reader_get_current_type (const DBusTypeReader *reader)
   return t;
 }
 
+/**
+ * Gets the type of an element of the array the reader is currently
+ * pointing to. It's an error to call this if
+ * _dbus_type_reader_get_current_type() doesn't return #DBUS_TYPE_ARRAY
+ * for this reader.
+ *
+ * @param reader the reader
+ */
 int
-_dbus_type_reader_get_array_type (const DBusTypeReader  *reader)
+_dbus_type_reader_get_element_type (const DBusTypeReader  *reader)
 {
   int element_type;
 
@@ -770,36 +838,25 @@ _dbus_type_reader_get_array_type (const DBusTypeReader  *reader)
   return element_type;
 }
 
+/**
+ * Gets the current position in the value block
+ * @param reader the reader
+ */
 int
 _dbus_type_reader_get_value_pos (const DBusTypeReader  *reader)
 {
   return reader->value_pos;
 }
 
-dbus_bool_t
+/**
+ * Checks whether an array has any elements.
+ *
+ * @param reader the reader
+ */
+static dbus_bool_t
 _dbus_type_reader_array_is_empty (const DBusTypeReader *reader)
 {
-  dbus_uint32_t array_len;
-
-  _dbus_assert (_dbus_type_reader_get_current_type (reader) == DBUS_TYPE_ARRAY);
-  _dbus_assert (!reader->klass->types_only);
-
-  /* reader is supposed to be at an array child */
-#if RECURSIVE_MARSHAL_READ_TRACE
-   _dbus_verbose ("checking array len at %d\n", reader->value_pos);
-#endif
-
-   _dbus_marshal_read_basic (reader->value_str,
-                             reader->value_pos,
-                             DBUS_TYPE_UINT32,
-                             &array_len,
-                             reader->byte_order,
-                             NULL);
-#if RECURSIVE_MARSHAL_READ_TRACE
-  _dbus_verbose (" ... array len = %d\n", array_len);
-#endif
-
-  return array_len == 0;
+  return array_reader_get_array_len (reader) == 0;
 }
 
 /**
@@ -822,6 +879,12 @@ _dbus_type_reader_read_raw (const DBusTypeReader  *reader,
                                                      0);
 }
 
+/**
+ * Reads a basic-typed value, as with _dbus_marshal_read_basic().
+ *
+ * @param reader the reader
+ * @param value the address of the value
+ */
 void
 _dbus_type_reader_read_basic (const DBusTypeReader    *reader,
                               void                    *value)
@@ -1852,7 +1915,7 @@ writer_recurse_array (DBusTypeWriter   *writer,
                                      _dbus_string_get_const_data_len (sub->value_str,
                                                                       sub->u.array.len_pos,
                                                                       4));
-          
+
           sub->value_pos += len;
         }
     }
@@ -2006,6 +2069,16 @@ _dbus_type_writer_recurse_contained_len (DBusTypeWriter   *writer,
     }
 }
 
+/**
+ * Opens a new container and writes out the initial information for that container.
+ *
+ * @param writer the writer
+ * @param container_type the type of the container to open
+ * @param contained_type the array element type or variant content type
+ * @param contained_type_start position to look for the type
+ * @param sub the new sub-writer to write container contents
+ * @returns #FALSE if no memory
+ */
 dbus_bool_t
 _dbus_type_writer_recurse (DBusTypeWriter   *writer,
                            int               container_type,
@@ -2068,6 +2141,14 @@ writer_get_array_len (DBusTypeWriter *writer)
   return writer->value_pos - writer->u.array.start_pos;
 }
 
+/**
+ * Closes a container created by _dbus_type_writer_recurse()
+ * and writes any additional information to the values block.
+ *
+ * @param writer the writer
+ * @param sub the sub-writer created by _dbus_type_writer_recurse()
+ * @returns #FALSE if no memory
+ */
 dbus_bool_t
 _dbus_type_writer_unrecurse (DBusTypeWriter *writer,
                              DBusTypeWriter *sub)
@@ -2182,6 +2263,14 @@ _dbus_type_writer_unrecurse (DBusTypeWriter *writer,
   return TRUE;
 }
 
+/**
+ * Writes out a basic type.
+ *
+ * @param writer the writer
+ * @param type the type to write
+ * @param value the address of the value to write
+ * @returns #FALSE if no memory
+ */
 dbus_bool_t
 _dbus_type_writer_write_basic (DBusTypeWriter *writer,
                                int             type,
@@ -2452,7 +2541,7 @@ writer_write_reader_helper (DBusTypeWriter       *writer,
 
               _dbus_assert (_DBUS_ALIGN_VALUE (fixup.len_pos_in_reader, 4) ==
                             (unsigned) fixup.len_pos_in_reader);
-              
+
               old_len = _dbus_unpack_uint32 (reader->byte_order,
                                              _dbus_string_get_const_data_len (reader->value_str,
                                                                               fixup.len_pos_in_reader, 4));
@@ -3515,7 +3604,6 @@ typedef struct
   int                 n_nodes;
 } NodeIterationData;
 
-
 static dbus_bool_t
 run_test_copy (NodeIterationData *nid)
 {
@@ -5345,7 +5433,7 @@ array_read_or_set_value (TestTypeNode   *node,
       _dbus_type_reader_recurse (reader, &sub);
 
       if (realign_root == NULL && arrays_write_fixed_in_blocks &&
-          _dbus_type_is_fixed (_dbus_type_reader_get_array_type (reader)) &&
+          _dbus_type_is_fixed (_dbus_type_reader_get_element_type (reader)) &&
           child->klass->read_multi)
         {
           if (!node_read_multi (child, &sub, seed, n_copies))
@@ -5365,7 +5453,7 @@ array_read_or_set_value (TestTypeNode   *node,
                   DBusList *next = _dbus_list_get_next_link (&container->children, link);
 
                   _dbus_assert (child->klass->typecode ==
-                                _dbus_type_reader_get_array_type (reader));
+                                _dbus_type_reader_get_element_type (reader));
 
                   if (realign_root == NULL)
                     {
diff --git a/dbus/dbus-marshal-recursive.h b/dbus/dbus-marshal-recursive.h
index 203e2f8c..fe9e1426 100644
--- a/dbus/dbus-marshal-recursive.h
+++ b/dbus/dbus-marshal-recursive.h
@@ -57,75 +57,88 @@ typedef struct DBusTypeWriter      DBusTypeWriter;
 typedef struct DBusTypeReaderClass DBusTypeReaderClass;
 typedef struct DBusArrayLenFixup   DBusArrayLenFixup;
 
-/* The mark is a way to compress a TypeReader; it isn't all that
+/** The mark is a way to compress a #DBusTypeReader; it isn't all that
  * successful though. The idea was to use this for caching header
  * fields in dbus-message.c. However now I'm thinking why not cache
  * the actual values (e.g. char*) and if the field needs to be set or
  * deleted, just linear search for it. Those operations are uncommon,
  * and getting the values should be fast and not involve all this type
  * reader nonsense.
+ *
+ * @todo DBusTypeMark isn't used right now and probably won't be, we should delete it
  */
 struct DBusTypeMark
 {
-  dbus_uint32_t type_pos_in_value_str : 1;
-  dbus_uint32_t container_type : 3;
-  dbus_uint32_t array_len_offset : 3; /* bytes back from start_pos that len ends */
-  dbus_uint32_t type_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
-  dbus_uint32_t value_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
-  dbus_uint32_t array_start_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS;
+  dbus_uint32_t type_pos_in_value_str : 1; /**< true if the type_pos is in value_str and not type_str */
+  dbus_uint32_t container_type : 3; /**< the "id" of the container type */
+  dbus_uint32_t array_len_offset : 3; /**< bytes back from start_pos that len ends */
+  dbus_uint32_t type_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< position in type_str */
+  dbus_uint32_t value_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< position in value_str */
+  dbus_uint32_t array_start_pos : DBUS_MAXIMUM_MESSAGE_LENGTH_BITS; /**< start of the array the reader was iterating over */
 };
 
+/**
+ * The type reader is an iterator for reading values from a block of
+ * values.
+ */
 struct DBusTypeReader
 {
-  dbus_uint32_t byte_order : 8;
+  dbus_uint32_t byte_order : 8; /**< byte order of the block */
 
-  dbus_uint32_t finished : 1;   /* marks we're at end iterator for cases
+  dbus_uint32_t finished : 1;   /**< marks we're at end iterator for cases
                                  * where we don't have another way to tell
                                  */
-  dbus_uint32_t array_len_offset : 3; /* bytes back from start_pos that len ends */
-  const DBusString *type_str;
-  int type_pos;
-  const DBusString *value_str;
-  int value_pos;
+  dbus_uint32_t array_len_offset : 3; /**< bytes back from start_pos that len ends */
+  const DBusString *type_str;   /**< string containing signature of block */
+  int type_pos;                 /**< current position in signature */
+  const DBusString *value_str;  /**< string containing values of block */
+  int value_pos;                /**< current position in values */
 
-  const DBusTypeReaderClass *klass;
+  const DBusTypeReaderClass *klass; /**< the vtable for the reader */
   union
   {
     struct {
-      int start_pos;
+      int start_pos;                /**< for array readers, the start of the array values */
     } array;
-  } u;
+  } u; /**< class-specific data */
 };
 
+/**
+ * The type writer is an iterator for writing to a block of values.
+ */
 struct DBusTypeWriter
 {
-  dbus_uint32_t byte_order : 8;
+  dbus_uint32_t byte_order : 8;            /**< byte order to write values with */
 
-  dbus_uint32_t container_type : 8;
+  dbus_uint32_t container_type : 8;        /**< what are we inside? (e.g. struct, variant, array) */
 
-  dbus_uint32_t type_pos_is_expectation : 1; /* type_pos is an insertion point or an expected next type */
+  dbus_uint32_t type_pos_is_expectation : 1; /**< type_pos can be either an insertion point for or an expected next type */
 
-  dbus_uint32_t enabled : 1; /* whether to write values */
+  dbus_uint32_t enabled : 1; /**< whether to write values */
 
-  DBusString *type_str;
-  int type_pos;
-  DBusString *value_str;
-  int value_pos;
+  DBusString *type_str; /**< where to write typecodes (or read type expectations) */
+  int type_pos;         /**< current pos in type_str */
+  DBusString *value_str; /**< where to write values */
+  int value_pos;         /**< next position to write */
 
   union
   {
     struct {
-      int start_pos; /* first element */
-      int len_pos;
-      int element_type_pos; /* position of array element type in type_str */
+      int start_pos; /**< position of first element in the array */
+      int len_pos;   /**< position of length of the array */
+      int element_type_pos; /**< position of array element type in type_str */
     } array;
-  } u;
+  } u; /**< class-specific data */
 };
 
+/**
+ * When modifying an existing block of values, array lengths may need
+ * to be adjusted; those adjustments are described by this struct.
+ */
 struct DBusArrayLenFixup
 {
-  int len_pos_in_reader;
-  int new_len;
+  int len_pos_in_reader; /**< where the length was in the original block */
+  int new_len;           /**< the new value of the length in the written-out block */
 };
 
 void        _dbus_type_reader_init                      (DBusTypeReader        *reader,
@@ -148,9 +161,8 @@ void        _dbus_type_reader_init_types_only_from_mark (DBusTypeReader        *
 void        _dbus_type_reader_save_mark                 (const DBusTypeReader  *reader,
                                                          DBusTypeMark          *mark);
 int         _dbus_type_reader_get_current_type          (const DBusTypeReader  *reader);
-int         _dbus_type_reader_get_array_type            (const DBusTypeReader  *reader);
+int         _dbus_type_reader_get_element_type          (const DBusTypeReader  *reader);
 int         _dbus_type_reader_get_value_pos             (const DBusTypeReader  *reader);
-dbus_bool_t _dbus_type_reader_array_is_empty            (const DBusTypeReader  *reader);
 void        _dbus_type_reader_read_basic                (const DBusTypeReader  *reader,
                                                          void                  *value);
 void        _dbus_type_reader_read_fixed_multi          (const DBusTypeReader  *reader,
diff --git a/dbus/dbus-marshal-validate.c b/dbus/dbus-marshal-validate.c
index cf409758..d3507739 100644
--- a/dbus/dbus-marshal-validate.c
+++ b/dbus/dbus-marshal-validate.c
@@ -203,7 +203,7 @@ validate_body_helper (DBusTypeReader       *reader,
 
             if (current_type == DBUS_TYPE_ARRAY)
               {
-                int array_elem_type = _dbus_type_reader_get_array_type (reader);
+                int array_elem_type = _dbus_type_reader_get_element_type (reader);
                 alignment = _dbus_type_get_alignment (array_elem_type);
                 p = _DBUS_ALIGN_ADDRESS (p, alignment);
               }
@@ -419,6 +419,7 @@ validate_body_helper (DBusTypeReader       *reader,
  * @param expected_signature_start where in expected_signature is the signature
  * @param byte_order the byte order
  * @param bytes_remaining place to store leftover bytes
+ * @param value_str the string containing the body
  * @param value_pos where the values start
  * @param len length of values after value_pos
  * @returns #DBUS_VALID if valid, reason why invalid otherwise
@@ -814,14 +815,17 @@ _dbus_validate_signature (const DBusString  *str,
   return _dbus_validate_signature_with_reason (str, start, len) == DBUS_VALID;
 }
 
-/* If the compiler hates these semicolons, add "extern int
- * allow_parens" at the end in the the macro perhaps
- */
+/** define _dbus_check_is_valid_path() */
 DEFINE_DBUS_NAME_CHECK(path);
+/** define _dbus_check_is_valid_interface() */
 DEFINE_DBUS_NAME_CHECK(interface);
+/** define _dbus_check_is_valid_member() */
 DEFINE_DBUS_NAME_CHECK(member);
+/** define _dbus_check_is_valid_error_name() */
 DEFINE_DBUS_NAME_CHECK(error_name);
+/** define _dbus_check_is_valid_service() */
 DEFINE_DBUS_NAME_CHECK(service);
+/** define _dbus_check_is_valid_signature() */
 DEFINE_DBUS_NAME_CHECK(signature);
 
 /** @} */
diff --git a/dbus/dbus-marshal-validate.h b/dbus/dbus-marshal-validate.h
index 8f4e7ef6..a4950dbe 100644
--- a/dbus/dbus-marshal-validate.h
+++ b/dbus/dbus-marshal-validate.h
@@ -132,12 +132,14 @@ dbus_bool_t _dbus_validate_signature  (const DBusString *str,
 
 #else /* !DBUS_DISABLE_CHECKS */
 
-/* A name check is used in _dbus_return_if_fail(), it's not suitable
+/** A name check is used in _dbus_return_if_fail(), it's not suitable
  * for validating untrusted data. use _dbus_validate_##what for that.
  */
 #define DECLARE_DBUS_NAME_CHECK(what) \
 dbus_bool_t _dbus_check_is_valid_##what (const char *name)
 
+/** Define a name check to be used in _dbus_return_if_fail() statements.
+ */
 #define DEFINE_DBUS_NAME_CHECK(what)                                    \
 dbus_bool_t                                                             \
 _dbus_check_is_valid_##what (const char *name)                          \
diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 8cb3dc64..70e1d022 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -55,8 +55,10 @@ static dbus_bool_t dbus_message_iter_get_args_valist (DBusMessageIter *iter,
 
 /* Not thread locked, but strictly const/read-only so should be OK
  */
+/** An static string representing an empty signature */
 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str,  "");
 
+/** How many bits are in the changed_stamp used to validate iterators */
 #define CHANGED_STAMP_BITS 21
 
 /**
@@ -114,9 +116,9 @@ struct DBusMessageRealIter
   dbus_uint32_t sig_refcount : 8;   /**< depth of open_signature() */
   union
   {
-    DBusTypeWriter writer;
-    DBusTypeReader reader;
-  } u;
+    DBusTypeWriter writer; /**< writer */
+    DBusTypeReader reader; /**< reader */
+  } u; /**< the type writer or reader that does all the work */
 };
 
 /**
@@ -515,9 +517,10 @@ dbus_message_finalize (DBusMessage *message)
  * mempool).
  */
 
-/* Avoid caching huge messages */
+/** Avoid caching huge messages */
 #define MAX_MESSAGE_SIZE_TO_CACHE _DBUS_ONE_MEGABYTE
-/* Avoid caching too many messages */
+
+/** Avoid caching too many messages */
 #define MAX_MESSAGE_CACHE_SIZE    5
 
 _DBUS_DEFINE_GLOBAL_LOCK (message_cache);
@@ -949,7 +952,7 @@ dbus_message_new_error (DBusMessage *reply_to,
 
   if (error_message != NULL)
     {
-      dbus_message_append_iter_init (message, &iter);
+      dbus_message_iter_init_append (message, &iter);
       if (!dbus_message_iter_append_basic (&iter,
                                            DBUS_TYPE_STRING,
                                            &error_message))
@@ -1232,7 +1235,7 @@ dbus_message_append_args_valist (DBusMessage *message,
 
   type = first_arg_type;
 
-  dbus_message_append_iter_init (message, &iter);
+  dbus_message_iter_init_append (message, &iter);
 
   while (type != DBUS_TYPE_INVALID)
     {
@@ -1574,7 +1577,7 @@ dbus_message_iter_get_arg_type (DBusMessageIter *iter)
  * @returns the array element type
  */
 int
-dbus_message_iter_get_array_type (DBusMessageIter *iter)
+dbus_message_iter_get_element_type (DBusMessageIter *iter)
 {
   DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
 
@@ -1582,7 +1585,7 @@ dbus_message_iter_get_array_type (DBusMessageIter *iter)
   _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
   _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
 
-  return _dbus_type_reader_get_array_type (&real->u.reader);
+  return _dbus_type_reader_get_element_type (&real->u.reader);
 }
 
 /**
@@ -1685,7 +1688,7 @@ dbus_message_iter_get_fixed_array (DBusMessageIter  *iter,
 
   _dbus_return_if_fail (_dbus_message_iter_check (real));
   _dbus_return_if_fail (value != NULL);
-  _dbus_return_if_fail (_dbus_type_is_fixed (_dbus_type_reader_get_array_type (&real->u.reader)));
+  _dbus_return_if_fail (_dbus_type_is_fixed (_dbus_type_reader_get_element_type (&real->u.reader)));
 
   _dbus_type_reader_read_fixed_multi (&real->u.reader,
                                       value, n_elements);
@@ -1760,7 +1763,7 @@ dbus_message_iter_get_args_valist (DBusMessageIter *iter,
           DBusTypeReader array;
 
           spec_element_type = va_arg (var_args, int);
-          element_type = _dbus_type_reader_get_array_type (&real->u.reader);
+          element_type = _dbus_type_reader_get_element_type (&real->u.reader);
 
           if (spec_element_type != element_type)
             {
@@ -1894,7 +1897,7 @@ dbus_message_iter_get_args_valist (DBusMessageIter *iter,
  * @param iter pointer to an iterator to initialize
  */
 void
-dbus_message_append_iter_init (DBusMessage     *message,
+dbus_message_iter_init_append (DBusMessage     *message,
 			       DBusMessageIter *iter)
 {
   DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
@@ -2115,7 +2118,7 @@ dbus_message_iter_append_basic (DBusMessageIter *iter,
  * you have to start over building the whole message.
  *
  * @param iter the append iterator
- * @param type the type of the array elements
+ * @param element_type the type of the array elements
  * @param value the address of the array
  * @param n_elements the number of elements to append
  * @returns #FALSE if not enough memory
@@ -4596,7 +4599,7 @@ _dbus_message_test (const char *test_data_dir)
   _dbus_message_set_serial (message, 1);
   dbus_message_set_reply_serial (message, 0x12345678);
 
-  dbus_message_append_iter_init (message, &iter);
+  dbus_message_iter_init_append (message, &iter);
   dbus_message_iter_append_string (&iter, "Test string");
   dbus_message_iter_append_int32 (&iter, -0x12345678);
   dbus_message_iter_append_uint32 (&iter, 0xedd1e);
diff --git a/dbus/dbus-message.h b/dbus/dbus-message.h
index fd6b96d4..7dcedcc7 100644
--- a/dbus/dbus-message.h
+++ b/dbus/dbus-message.h
@@ -1,7 +1,7 @@
 /* -*- mode: C; c-file-style: "gnu" -*- */
 /* dbus-message.h DBusMessage object
  *
- * Copyright (C) 2002, 2003 Red Hat Inc.
+ * Copyright (C) 2002, 2003, 2005 Red Hat Inc.
  *
  * Licensed under the Academic Free License version 2.1
  * 
@@ -146,21 +146,22 @@ dbus_bool_t dbus_message_get_args_valist      (DBusMessage     *message,
 					       va_list          var_args);
 
 
-dbus_bool_t            dbus_message_iter_init            (DBusMessage      *message,
-                                                          DBusMessageIter  *iter);
-dbus_bool_t            dbus_message_iter_has_next        (DBusMessageIter  *iter);
-dbus_bool_t            dbus_message_iter_next            (DBusMessageIter  *iter);
-int                    dbus_message_iter_get_arg_type    (DBusMessageIter  *iter);
-int                    dbus_message_iter_get_array_type  (DBusMessageIter  *iter);
-void                   dbus_message_iter_recurse         (DBusMessageIter  *iter,
-                                                          DBusMessageIter  *sub);
-void                   dbus_message_iter_get_basic       (DBusMessageIter  *iter,
-                                                          void             *value);
-void                   dbus_message_iter_get_fixed_array (DBusMessageIter  *iter,
-                                                          void             *value,
-                                                          int              *n_elements);
-
-void        dbus_message_append_iter_init        (DBusMessage     *message,
+dbus_bool_t dbus_message_iter_init             (DBusMessage     *message,
+                                                DBusMessageIter *iter);
+dbus_bool_t dbus_message_iter_has_next         (DBusMessageIter *iter);
+dbus_bool_t dbus_message_iter_next             (DBusMessageIter *iter);
+int         dbus_message_iter_get_arg_type     (DBusMessageIter *iter);
+int         dbus_message_iter_get_element_type (DBusMessageIter *iter);
+void        dbus_message_iter_recurse          (DBusMessageIter *iter,
+                                                DBusMessageIter *sub);
+void        dbus_message_iter_get_basic        (DBusMessageIter *iter,
+                                                void            *value);
+void        dbus_message_iter_get_fixed_array  (DBusMessageIter *iter,
+                                                void            *value,
+                                                int             *n_elements);
+
+
+void        dbus_message_iter_init_append        (DBusMessage     *message,
                                                   DBusMessageIter *iter);
 dbus_bool_t dbus_message_iter_append_basic       (DBusMessageIter *iter,
                                                   int              type,
diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c
index dccf5176..52099d65 100644
--- a/dbus/dbus-string.c
+++ b/dbus/dbus-string.c
@@ -809,7 +809,7 @@ _dbus_string_copy_data_len (const DBusString  *str,
  * 
  * @param str a string
  * @param buffer a C buffer to copy data to
- * @param len maximum length of C buffer
+ * @param avail_len maximum length of C buffer
  */
 void
 _dbus_string_copy_to_buffer (const DBusString  *str,
@@ -1046,13 +1046,16 @@ _dbus_string_append (DBusString *str,
   return append (real, buffer, buffer_len);
 }
 
+/** assign 4 bytes from one string to another */
 #define ASSIGN_4_OCTETS(p, octets) \
   *((dbus_uint32_t*)(p)) = *((dbus_uint32_t*)(octets));
 
 #ifdef DBUS_HAVE_INT64
+/** assign 8 bytes from one string to another */
 #define ASSIGN_8_OCTETS(p, octets) \
   *((dbus_uint64_t*)(p)) = *((dbus_uint64_t*)(octets));
 #else
+/** assign 8 bytes from one string to another */
 #define ASSIGN_8_OCTETS(p, octets)              \
 do {                                            \
   unsigned char *b;                             \
@@ -1120,6 +1123,7 @@ _dbus_string_append_8_aligned (DBusString         *str,
  * with any alignment padding initialized to 0.
  *
  * @param str the DBusString
+ * @param insert_at where to insert
  * @param octets 4 bytes to insert
  * @returns #FALSE if not enough memory.
  */
@@ -1143,6 +1147,7 @@ _dbus_string_insert_4_aligned (DBusString         *str,
  * with any alignment padding initialized to 0.
  *
  * @param str the DBusString
+ * @param insert_at where to insert
  * @param octets 8 bytes to insert
  * @returns #FALSE if not enough memory.
  */