[evolution-patches] More API docs -- e-time-utils and e-xml-hash-utils

[James Bowes <bowes cs dal ca>]

Here's more API documentation for libeds, this time for e-time-utils and
e-xml-hash-utils. Additionally, I've moved the existing section
information (title, short description) for e-trie, e-util, e-url, e-uid,
and md5-utils into in-line comments in the C files, rather than having
them scattered about in various SGML files in the reference dir.

-James

Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/evolution-data-server/ChangeLog,v
retrieving revision 1.236
diff -u -r1.236 ChangeLog
--- ChangeLog	27 Mar 2005 12:32:59 -0000	1.236
+++ ChangeLog	28 Mar 2005 16:56:02 -0000
@@ -1,3 +1,26 @@
+2005-03-28  James Bowes  <bowes cs dal ca>
+
+	* docs/reference/libedataserver/libedataserver-docs.sgml:
+	* docs/reference/libedataserver/libedataserver-sections.txt: Add
+	e-time-utils and e-xml-hash-utils.
+	* docs/reference/libedataserver/tmpl/e-trie.sgml:
+	* docs/reference/libedataserver/tmpl/e-uid.sgml:
+	* docs/reference/libedataserver/tmpl/e-url.sgml:
+	* docs/reference/libedataserver/tmpl/e-util.sgml:
+	* docs/reference/libedataserver/tmpl/md5-utils.sgml: Move existing 
+	content from sgml template files to inline comments.
+	* libedataserver/e-time-utils.c:
+	* libedataserver/e-time-utils.h: New API documentation.
+	* libedataserver/e-trie.c:
+	* libedataserver/e-uid.c:
+	* libedataserver/e-url.c:
+	* libedataserver/e-util.c: Section information moved to inline 
+	comments.
+	* libedataserver/e-xml-hash-utils.c:
+	* libedataserver/e-xml-hash-utils.h: New API documentation.
+	* libedataserver/md5-utils.c: Section information moved to inline
+	comments.
+
 2005-03-27  Pawan Chitrakar  <pawan nplinux org>
 
 	* configure.in: Add ne in ALL_LINGUAS
Index: docs/reference/libedataserver/libedataserver-docs.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/libedataserver-docs.sgml,v
retrieving revision 1.2
diff -u -r1.2 libedataserver-docs.sgml
--- docs/reference/libedataserver/libedataserver-docs.sgml	24 Mar 2005 18:23:36 -0000	1.2
+++ docs/reference/libedataserver/libedataserver-docs.sgml	28 Mar 2005 16:56:02 -0000
@@ -9,9 +9,11 @@
   <chapter>
     <title>Evolution API Reference: libedataserver, utility library</title>
     <!--<xi:include href="xml/e-cal-view.xml"/>-->
+    <xi:include href="xml/e-time-utils.xml"/>
     <xi:include href="xml/e-trie.xml"/>
     <xi:include href="xml/e-util.xml"/>
     <xi:include href="xml/e-url.xml"/>
+    <xi:include href="xml/e-xml-hash-utils.xml"/>
     <xi:include href="xml/md5-utils.xml"/>
   </chapter>
 </book>
Index: docs/reference/libedataserver/libedataserver-sections.txt
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/libedataserver-sections.txt,v
retrieving revision 1.3
diff -u -r1.3 libedataserver-sections.txt
--- docs/reference/libedataserver/libedataserver-sections.txt	24 Mar 2005 18:23:36 -0000	1.3
+++ docs/reference/libedataserver/libedataserver-sections.txt	28 Mar 2005 16:56:02 -0000
@@ -1,7 +1,22 @@
 <SECTION>
+<FILE>e-time-utils</FILE>
+<INCLUDE>libedataserver/e-time-utils.h</INCLUDE>
+ETimeParseStatus
+<SUBSECTION>
+e_time_parse_date_and_time
+e_time_parse_date
+e_time_parse_time
+<SUBSECTION>
+e_time_format_date_and_time
+e_time_format_time
+<SUBSECTION>
+e_mktime_utc
+e_localtime_with_offset
+</SECTION>
+
+<SECTION>
 <FILE>e-trie</FILE>
 <INCLUDE>libedataserver/e-trie.h</INCLUDE>
-<TITLE>ETrie</TITLE>
 ETrie
 <SUBSECTION>
 e_trie_new
@@ -14,14 +29,12 @@
 <SECTION>
 <FILE>e-uid</FILE>
 <INCLUDE>libedataserver/e-uid.h</INCLUDE>
-<TITLE>User ID Generation</TITLE>
 e_uid_new
 </SECTION>
 
 <SECTION>
 <FILE>e-util</FILE>
 <INCLUDE>libedataserver/e-util.h</INCLUDE>
-<TITLE>Utility Functions</TITLE>
 e_util_mkdir_hier
 <SUBSECTION>
 e_util_strstrcase
@@ -36,7 +49,6 @@
 <SECTION>
 <FILE>e-url</FILE>
 <INCLUDE>libedataserver/e-url.h</INCLUDE>
-<TITLE>EUrl</TITLE>
 EUri
 <SUBSECTION>
 e_url_shroud
@@ -52,9 +64,34 @@
 </SECTION>
 
 <SECTION>
+<FILE>e-xml-hash-utils</FILE>
+<INCLUDE>libedataserver/e-xml-hash-utils.h</INCLUDE>
+EXmlHash
+<SUBSECTION>
+EXmlHashType
+EXmlHashStatus
+<SUBSECTION>
+EXmlHashFunc
+<SUBSECTION>
+e_xml_to_hash
+e_xml_from_hash
+e_xml_destroy_hash
+<SUBSECTION>
+e_xmlhash_new
+<SUBSECTION>
+e_xmlhash_add
+e_xmlhash_remove
+<SUBSECTION>
+e_xmlhash_compare
+e_xmlhash_foreach_key
+<SUBSECTION>
+e_xmlhash_write
+e_xmlhash_destroy
+</SECTION>
+
+<SECTION>
 <FILE>md5-utils</FILE>
 <INCLUDE>libedataserver/md5-utils.h</INCLUDE>
-<TITLE>MD5 Utility Functions</TITLE>
 MD5Context
 <SUBSECTION>
 md5_get_digest
Index: docs/reference/libedataserver/tmpl/e-trie.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/tmpl/e-trie.sgml,v
retrieving revision 1.1
diff -u -r1.1 e-trie.sgml
--- docs/reference/libedataserver/tmpl/e-trie.sgml	24 Mar 2005 18:23:36 -0000	1.1
+++ docs/reference/libedataserver/tmpl/e-trie.sgml	28 Mar 2005 16:56:02 -0000
@@ -1,8 +1,6 @@
 <!-- ##### SECTION Title ##### -->
-ETrie
 
 <!-- ##### SECTION Short_Description ##### -->
-A trie data structure.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
Index: docs/reference/libedataserver/tmpl/e-uid.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/tmpl/e-uid.sgml,v
retrieving revision 1.1
diff -u -r1.1 e-uid.sgml
--- docs/reference/libedataserver/tmpl/e-uid.sgml	24 Mar 2005 18:23:36 -0000	1.1
+++ docs/reference/libedataserver/tmpl/e-uid.sgml	28 Mar 2005 16:56:02 -0000
@@ -1,8 +1,6 @@
 <!-- ##### SECTION Title ##### -->
-User ID Generation
 
 <!-- ##### SECTION Short_Description ##### -->
-Generate unique UIDs.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
Index: docs/reference/libedataserver/tmpl/e-url.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/tmpl/e-url.sgml,v
retrieving revision 1.1
diff -u -r1.1 e-url.sgml
--- docs/reference/libedataserver/tmpl/e-url.sgml	24 Mar 2005 18:23:36 -0000	1.1
+++ docs/reference/libedataserver/tmpl/e-url.sgml	28 Mar 2005 16:56:02 -0000
@@ -1,8 +1,6 @@
 <!-- ##### SECTION Title ##### -->
-EUrl
 
 <!-- ##### SECTION Short_Description ##### -->
-A URI data structure and associated functions.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
Index: docs/reference/libedataserver/tmpl/e-util.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/tmpl/e-util.sgml,v
retrieving revision 1.1
diff -u -r1.1 e-util.sgml
--- docs/reference/libedataserver/tmpl/e-util.sgml	24 Mar 2005 18:23:36 -0000	1.1
+++ docs/reference/libedataserver/tmpl/e-util.sgml	28 Mar 2005 16:56:02 -0000
@@ -1,8 +1,6 @@
 <!-- ##### SECTION Title ##### -->
-Utility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-Miscellaneous utility functions for evolution-data-server.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
Index: docs/reference/libedataserver/tmpl/md5-utils.sgml
===================================================================
RCS file: /cvs/gnome/evolution-data-server/docs/reference/libedataserver/tmpl/md5-utils.sgml,v
retrieving revision 1.1
diff -u -r1.1 md5-utils.sgml
--- docs/reference/libedataserver/tmpl/md5-utils.sgml	24 Mar 2005 18:23:36 -0000	1.1
+++ docs/reference/libedataserver/tmpl/md5-utils.sgml	28 Mar 2005 16:56:02 -0000
@@ -1,8 +1,6 @@
 <!-- ##### SECTION Title ##### -->
-MD5 Utility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-Functions for manipulating MD5 checksums.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
Index: libedataserver/e-time-utils.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-time-utils.c,v
retrieving revision 1.3
diff -u -r1.3 e-time-utils.c
--- libedataserver/e-time-utils.c	3 Feb 2005 16:35:01 -0000	1.3
+++ libedataserver/e-time-utils.c	28 Mar 2005 16:56:02 -0000
@@ -8,6 +8,13 @@
  * (C) 2001 Ximian, Inc.
  */
 
+/**
+ * SECTION:e-time-utils
+ * @title: Time-Related Utility Functions
+ * @short_description: Utility functions for time structure manipulation.
+ *
+ **/
+
 #include <config.h>
 
 #ifdef __linux__
@@ -124,15 +131,21 @@
 }
 
 
-/*
- * Parses a string containing a date and a time. The date is expected to be
- * in a format something like "Wed 3/13/00 14:20:00", though we use gettext
- * to support the appropriate local formats and we try to accept slightly
- * different formats, e.g. the weekday can be skipped and we can accept 12-hour
- * formats with an am/pm string.
+/**
+ * e_time_parse_date_and_time:
+ * @value: The string to parse a date and time from.
+ * @result: A #tm to store the result in.
+ *
+ * Parses a string @value containing a date and a time and stores the
+ * result in @result. The date in @value is expected to be in a format
+ * like "Wed 3/13/00 14:20:00", though gettext() is used to support the
+ * appropriate local formats. There is also some leniency on the
+ * format of the string, e.g. the weekday can be skipped or 12-hour
+ * formats with am/pm can be used.
  *
- * Returns E_TIME_PARSE_OK if it could not be parsed, E_TIME_PARSE_NONE if it
- * was empty, or E_TIME_PARSE_INVALID if it couldn't be parsed.
+ * Returns: E_TIME_PARSE_OK if the string was successfully parsed,
+ *          E_TIME_PARSE_NONE if the string was empty, or 
+ *          E_TIME_PARSE_INVALID if the string could not be parsed.
  */
 ETimeParseStatus
 e_time_parse_date_and_time		(const char	*value,
@@ -274,10 +287,10 @@
  * @result: Return value for the parsed date.
  * 
  * Takes in a date string entered by the user and tries to convert it to
- * a struct tm.
+ * a struct #tm.
  * 
- * Return value: Result code indicating whether the @value was an empty
- * string, a valid date, or an invalid date.
+ * Returns: An #ETimeParseStatus result code indicating whether
+ * @value was an empty string, a valid date, or an invalid date.
  **/
 ETimeParseStatus
 e_time_parse_date (const char *value, struct tm *result)
@@ -316,15 +329,20 @@
 }
 
 
-/*
- * Parses a string containing a time. It is expected to be in a format
- * something like "14:20:00", though we use gettext to support the appropriate
- * local formats and we try to accept slightly different formats, e.g. we can
- * accept 12-hour formats with an am/pm string.
+/**
+ * e_time_parse_time:
+ * @value: The string to parse a time from.
+ * @result: A #tm to store the result in.
  *
- * Returns E_TIME_PARSE_OK if it could not be parsed, E_TIME_PARSE_NONE if it
- * was empty, or E_TIME_PARSE_INVALID if it couldn't be parsed.
- */
+ * Parses @value, a string containing a time. @value is expected to be
+ * in a format like "14:20:00". gettext() is used to
+ * support the appropriate local formats and slightly
+ * different formats, such as 12-hour formats with am/pm,
+ * are accepted as well.
+ *
+ * Returns: An #ETimeParseStatus result code indicating whether
+ * @value was an empty string, a valid date, or an invalid date.
+ **/
 ETimeParseStatus
 e_time_parse_time (const char *value, struct tm *result)
 {
@@ -361,11 +379,22 @@
 }
 
 
-/* Creates a string representation of a time value and stores it in buffer.
-   buffer_size should be about 64 to be safe. If show_midnight is FALSE, and
-   the time is midnight, then we just show the date. If show_zero_seconds
-   is FALSE, then if the time has zero seconds only the hour and minute are
-   shown. */
+/**
+ * e_time_format_date_and_time:
+ * @date_tm: The #tm to convert to a string.
+ * @use_24_hour_format: A #gboolean.
+ * @show_midnight: A #gboolean.
+ * @show_zero_seconds: A #gboolean.
+ * @buffer: A #char buffer to store the time string in.
+ * @buffer_size: The length of @buffer.
+ *
+ * Creates a string representation of the time value @date_tm and
+ * stores it in @buffer.  @buffer_size should be at least 64 to be
+ * safe. If @show_midnight is #FALSE, and the time is midnight, then
+ * only the date is stored in @buffer. If @show_zero_seconds is
+ * #FALSE, then if the time has zero seconds only the hour and minute
+ * of the time are stored in @buffer.
+ **/
 void
 e_time_format_date_and_time		(struct tm	*date_tm,
 					 gboolean	 use_24_hour_format,
@@ -407,8 +436,17 @@
 }
 
 
-/* Creates a string representation of a time value and stores it in buffer.
-   buffer_size should be about 64 to be safe. */
+/**
+ * e_time_format_time:
+ * @date_tm: The #tm to convert to a string.
+ * @use_24_hour_format: A #gboolean.
+ * @show_zero_seconds: A #gboolean.
+ * @buffer: The #char buffer to store the result in.
+ * @buffer_size: The length of @buffer.
+ *  
+ * Creates a string representation of a time value in @date_tm and
+ * stores it in @buffer. @buffer_size should be at least 64.
+ **/
 void
 e_time_format_time			(struct tm	*date_tm,
 					 gboolean	 use_24_hour_format,
@@ -443,7 +481,14 @@
 }
 
 
-/* Like mktime(3), but assumes UTC instead of local timezone. */
+/**
+ * e_mktime_utc:
+ * @tm: The #tm to convert to a calendar time representation.
+ * 
+ * Like mktime(3), but assumes UTC instead of local timezone.
+ * 
+ * Returns: The calendar time representation of @tm.
+ **/
 time_t
 e_mktime_utc (struct tm *tm)
 {
@@ -468,8 +513,16 @@
 	return tt;
 }
 
-/* Like localtime_r(3), but also returns an offset in seconds after UTC.
-   (Calling gmtime with tt + offset would generate the same tm) */
+/**
+ * e_localtime_with_offset:
+ * @tt: The #time_t to convert.
+ * @tm: The #tm to store the result in.
+ * @offset: The #int to store the offset in.
+ *
+ * Converts the calendar time time representation @tt to a broken-down
+ * time representation, store in @tm, and provides the offset in
+ * seconds from UTC time, stored in @offset.
+ **/
 void
 e_localtime_with_offset (time_t tt, struct tm *tm, int *offset)
 {
Index: libedataserver/e-time-utils.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-time-utils.h,v
retrieving revision 1.2
diff -u -r1.2 e-time-utils.h
--- libedataserver/e-time-utils.h	3 Dec 2004 03:33:06 -0000	1.2
+++ libedataserver/e-time-utils.h	28 Mar 2005 16:56:02 -0000
@@ -14,6 +14,12 @@
 #include <time.h>
 #include <glib.h>
 
+/**
+ * ETimeParseStatus:
+ * @E_TIME_PARSE_OK: The time string was parsed successfully.
+ * @E_TIME_PARSE_NONE: The time string was empty.
+ * @E_TIME_PARSE_INVALID: The time string was not formatted correctly.
+ **/ 
 typedef enum {
 	E_TIME_PARSE_OK,
 	E_TIME_PARSE_NONE,
@@ -49,7 +55,7 @@
 
 
 /* Like mktime(3), but assumes UTC instead of local timezone. */
-time_t e_mktime_utc (struct tm *timeptr);
+time_t e_mktime_utc (struct tm *tm);
 
 /* Like localtime_r(3), but also returns an offset in minutes after UTC.
    (Calling gmtime with tt + offset would generate the same tm) */
Index: libedataserver/e-trie.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-trie.c,v
retrieving revision 1.3
diff -u -r1.3 e-trie.c
--- libedataserver/e-trie.c	24 Mar 2005 18:23:36 -0000	1.3
+++ libedataserver/e-trie.c	28 Mar 2005 16:56:02 -0000
@@ -20,6 +20,12 @@
  *
  */
 
+/**
+ * SECTION:e-trie
+ * @title: ETrie
+ * @short_description: A trie data structure.
+ *
+ **/
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>
Index: libedataserver/e-uid.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-uid.c,v
retrieving revision 1.3
diff -u -r1.3 e-uid.c
--- libedataserver/e-uid.c	24 Mar 2005 18:23:36 -0000	1.3
+++ libedataserver/e-uid.c	28 Mar 2005 16:56:02 -0000
@@ -20,6 +20,13 @@
  * Author: Dan Winship <danw ximian com>
  */
 
+/**
+ * SECTION: e-uid
+ * @title: User ID Generation
+ * @short_description: Generate unique UIDs.
+ *
+ **/
+
 #include "e-uid.h"
 
 #include <string.h>
Index: libedataserver/e-url.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-url.c,v
retrieving revision 1.3
diff -u -r1.3 e-url.c
--- libedataserver/e-url.c	24 Mar 2005 18:23:36 -0000	1.3
+++ libedataserver/e-url.c	28 Mar 2005 16:56:02 -0000
@@ -25,6 +25,13 @@
  * USA.
  */
 
+/**
+ * SECTION:e-url
+ * @title: EUrl
+ * @short_description: A URI data structure and associated functions.
+ *
+ **/
+
 #include <config.h>
 #include <ctype.h>
 #include <stdlib.h>
Index: libedataserver/e-util.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-util.c,v
retrieving revision 1.6
diff -u -r1.6 e-util.c
--- libedataserver/e-util.c	24 Mar 2005 18:23:36 -0000	1.6
+++ libedataserver/e-util.c	28 Mar 2005 16:56:02 -0000
@@ -19,6 +19,14 @@
  * Authors: Rodrigo Moya <rodrigo ximian com>
  */
 
+/**
+ * SECTION:e-util
+ * @title: Utility Functions
+ * @short_description: Miscellaneous utility functions for 
+ *                     evolution-data-server.
+ *
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
Index: libedataserver/e-xml-hash-utils.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-xml-hash-utils.c,v
retrieving revision 1.6
diff -u -r1.6 e-xml-hash-utils.c
--- libedataserver/e-xml-hash-utils.c	12 Jan 2005 08:49:04 -0000	1.6
+++ libedataserver/e-xml-hash-utils.c	28 Mar 2005 16:56:02 -0000
@@ -17,6 +17,13 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:e-xml-hash-utils
+ * @title: EXmlHash
+ * @short_description: Functions for manipulating xml as a hash table.
+ *
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -30,6 +37,19 @@
 #include <libxml/xmlmemory.h>
 #include <libxml/entities.h>
 
+/**
+ * e_xml_to_hash:
+ * @doc: The #xmlDoc to store in a hash table. 
+ * @type: The value type to use as a key in the hash table.
+ *
+ * Creates a #GHashTable representation of the #xmlDoc @doc.
+ * If @type is * @E_XML_HASH_TYPE_PROPERTY, all XML nodes will be
+ * indexed in the #GHashTable by name. If @type is
+ * %E_XML_HASH_TYPE_OBJECT_UID, then XML objects will be indexed in
+ * the hash by their UID (other nodes will still be indexed by name).
+ *
+ * Returns: The newly-created #GHashTable representation of @doc.
+ **/
 GHashTable *
 e_xml_to_hash (xmlDoc *doc, EXmlHashType type)
 {
@@ -98,6 +118,18 @@
 	xmlAddChild (sd->root, new_node);
 }
 
+/**
+ * e_xml_from_hash:
+ * @hash: The #GHashTable to extract the XML from.
+ * @type: The #EXmlHashType used to store the XML.
+ * @root_name: The name to call the new #xmlDoc.
+ *
+ * Uses the key/value pair representation of an XML structure in @hash
+ * to build an equivalent #xmlDoc. This is the reverse of
+ * e_xml_to_hash().
+ *
+ * Returns: The #xmlDoc created from the data in @hash.
+ **/
 xmlDoc *
 e_xml_from_hash (GHashTable *hash, EXmlHashType type, const char *root_name)
 {
@@ -122,6 +154,12 @@
 	g_free (value);
 }
 
+/**
+ * e_xml_destroy_hash:
+ * @hash: The #GHashTable to destroy.
+ *
+ * Frees the memory used by @hash and its contents.
+ **/
 void
 e_xml_destroy_hash (GHashTable *hash)
 {
@@ -130,12 +168,26 @@
 }
 
 
-
+/**
+ * EXmlHash:
+ *
+ * A hash table representation of an XML file.
+ **/
 struct EXmlHash {
 	char *filename;
 	GHashTable *objects;
 };
 
+/**
+ * e_xmlhash_new:
+ * @filename: The name of an XML file.
+ *
+ * Creates a new #EXmlHash from the file @filename. If @filename does
+ * not already exist, an empty #EXmlHash will be created.
+ *
+ * Returns: The new #EXmlHash structure, or %NULL if unable to parse
+ *          @filename.
+ **/
 EXmlHash *
 e_xmlhash_new (const char *filename)
 {
@@ -163,6 +215,14 @@
 	return hash;
 }
 
+/**
+ * e_xmlhash_add:
+ * @hash: The #EXmlHash to add an entry to.
+ * @key: The key to use for the entry.
+ * @data: The value of the new entry.
+ *
+ * Adds a new key/value pair to the #EXmlHash @hash.
+ **/
 void
 e_xmlhash_add (EXmlHash *hash, const char *key, const char *data)
 {
@@ -174,6 +234,13 @@
 	g_hash_table_insert (hash->objects, g_strdup (key), g_strdup (data));
 }
 
+/**
+ * e_xmlhash_remove:
+ * @hash: The #EXmlHash to remove an entry from.
+ * @key: The key of the entry to remove.
+ *
+ * Remove the entry in @hash with key equal to @key, if it exists.
+ **/
 void
 e_xmlhash_remove (EXmlHash *hash, const char *key)
 {
@@ -190,6 +257,20 @@
 	}
 }
 
+/**
+ * e_xmlhash_compare:
+ * @hash: The #EXmlHash to compare against.
+ * @key: The key of the hash entry to compare with.
+ * @compare_data: The data to compare against the hash entry.
+ *
+ * Compares the value with key equal to @key in @hash against
+ * @compare_data.
+ *
+ * Returns: E_XMLHASH_STATUS_SAME if the value and @compare_data are
+ *          equal,E_XMLHASH_STATUS_DIFFERENT if they are different, or
+ *          E_XMLHASH_STATUS_NOT_FOUND if there is no entry in @hash with 
+ *          its key equal to @key.
+ **/
 EXmlHashStatus
 e_xmlhash_compare (EXmlHash *hash, const char *key, const char *compare_data)
 {
@@ -224,6 +305,14 @@
 	data->func ((const char *) key, (const char *) value, data->user_data);
 }
 
+/**
+ * e_xmlhash_foreach_key:
+ * @hash: An #EXmlHash.
+ * @func: The #EXmlHashFunc to execute on the data in @hash.
+ * @user_data: The data to pass to @func.
+ *
+ * Executes @func against each key/value pair in @hash.
+ **/
 void
 e_xmlhash_foreach_key (EXmlHash *hash, EXmlHashFunc func, gpointer user_data)
 {
@@ -237,6 +326,13 @@
 	g_hash_table_foreach (hash->objects, foreach_hash_func, &data);
 }
 
+/**
+ * e_xmlhash_write:
+ * @hash: The #EXmlHash to write.
+ *
+ * Writes the XML represented by @hash to the file originally passed
+ * to e_xmlhash_new().
+ **/
 void
 e_xmlhash_write (EXmlHash *hash)
 {
@@ -262,6 +358,12 @@
 	xmlFreeDoc (doc);
 }
 
+/**
+ * e_xmlhash_destroy:
+ * @hash: The #EXmlHash to destroy.
+ *
+ * Frees the memory associated with @hash.
+ **/
 void
 e_xmlhash_destroy (EXmlHash *hash)
 {
Index: libedataserver/e-xml-hash-utils.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/e-xml-hash-utils.h,v
retrieving revision 1.3
diff -u -r1.3 e-xml-hash-utils.h
--- libedataserver/e-xml-hash-utils.h	3 May 2004 16:44:56 -0000	1.3
+++ libedataserver/e-xml-hash-utils.h	28 Mar 2005 16:56:02 -0000
@@ -25,6 +25,11 @@
 
 G_BEGIN_DECLS
 
+/**
+ * EXmlHashType:
+ * @E_XML_HASH_TYPE_OBJECT_UID: Use the object UID as the hash key.
+ * @E_XML_HASH_TYPE_PROPERTY: Use the property name as the hash key.
+ **/
 typedef enum {
 	E_XML_HASH_TYPE_OBJECT_UID,
 	E_XML_HASH_TYPE_PROPERTY
@@ -40,6 +45,12 @@
 
 
 
+/**
+ * EXmlHashStatus:
+ * @E_XMLHASH_STATUS_SAME: The compared values are the same.
+ * @E_XMLHASH_STATUS_DIFFERENT: The compared values are different.
+ * @E_XMLHASH_STATUS_NOT_FOUND: The key to compare against was not found.
+ **/
 typedef enum {
 	E_XMLHASH_STATUS_SAME,
 	E_XMLHASH_STATUS_DIFFERENT,
Index: libedataserver/md5-utils.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/libedataserver/md5-utils.c,v
retrieving revision 1.2
diff -u -r1.2 md5-utils.c
--- libedataserver/md5-utils.c	24 Mar 2005 18:23:37 -0000	1.2
+++ libedataserver/md5-utils.c	28 Mar 2005 16:56:02 -0000
@@ -22,6 +22,12 @@
  * Modified October 1995 by Erik Troan for RPM
  */
 
+/**
+ * SECTION:md5-utils
+ * @title: MD5 Utility Functions
+ * @short_description: Functions for manipulating MD5 checksums.
+ *
+ **/
 
 #include <stdio.h>
 #include <string.h>