diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000..228eefd
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,276 @@
+# Doxyfile 1.5.6
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = Strophe
+PROJECT_NUMBER         = 1.0
+OUTPUT_DIRECTORY       = /Users/jack/Sources/libstrophe/docs/
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = src
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP         = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = YES
+EXTRACT_ANON_NSPACES   = YES
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = NO
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = NO
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    = 
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = /Users/jack/Sources/libstrophe/
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c
+RECURSIVE              = YES
+EXCLUDE                = examples \
+		       	 tests
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = .svn
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = NO
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = docs/footer.html
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = YES
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     = 
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = YES
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NONE
+TREEVIEW_WIDTH         = 250
+FORMULA_FONTSIZE       = 10
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = "VA_START(f)=" \
+		         "VA_SHIFT(v,t)=" \
+			 "MIN(p,q)=" \
+			 "MAX(p,q)=" \
+			 "char_to_int(p)=" \
+			 "GET_32BIT_LSB_FIRST(cp)=" \
+			 "PUT_32BIT_LSB_FIRST(cp, value)=" \
+			 "F1(x,y,z)=" \
+			 "F2(x,y,z)=" \
+			 "F3(x,y,z)=" \
+			 "F4(x,y,z)=" \
+			 "MD5STEP(f,w,x,y,z,data,s)=" \
+			 "rol(value,bits)=" \
+			 "blk0(i)=" \
+			 "blk(i)=" \
+			 "R0(v,w,x,y,z,i)=" \
+			 "R1(v,w,x,y,z,i)=" \
+			 "R2(v,w,x,y,z,i)=" \
+			 "R3(v,w,x,y,z,i)=" \
+			 "R4(v,w,x,y,z,i)="
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            = /Applications/Doxygen.app/Contents/Resources/
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_FONTNAME           = FreeSans
+DOT_FONTPATH           = 
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = /Applications/Doxygen.app/Contents/Resources/
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 1000
+DOT_TRANSPARENT        = YES
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO
diff --git a/docs/footer.html b/docs/footer.html
new file mode 100644
index 0000000..308b1d0
--- /dev/null
+++ b/docs/footer.html
@@ -0,0 +1,2 @@
+</body>
+</html>
diff --git a/src/auth.c b/src/auth.c
index a271433..3e5df9e 100644
--- a/src/auth.c
+++ b/src/auth.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file 
+ *  Authentication function and handlers.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -24,11 +28,32 @@
 #define strcasecmp stricmp
 #endif
 
-/* FIXME: these should be configurable */
+/* TODO: these should configurable at runtime on a per connection basis  */
+
+#ifndef FEATURES_TIMEOUT
+/** @def FEATURES_TIMEOUT
+ *  Time to wait for &lt;stream:features/&gt; stanza.
+ */
 #define FEATURES_TIMEOUT 15000 /* 15 seconds */
+#endif
+#ifndef BIND_TIMEOUT
+/** @def BIND_TIMEOUT
+ *  Time to wait for &lt;bind/&gt; stanza reply.
+ */
 #define BIND_TIMEOUT 15000 /* 15 seconds */
+#endif
+#ifndef SESSION_TIMEOUT
+/** @def SESSION_TIMEOUT
+ *  Time to wait for &lt;session/&gt; stanza reply.
+ */
 #define SESSION_TIMEOUT 15000 /* 15 seconds */
+#endif
+#ifndef LEGACY_TIMEOUT
+/** @def LEGACY_TIMEOUT
+ *  Time to wait for legacy authentication to complete.
+ */
 #define LEGACY_TIMEOUT 15000 /* 15 seconds */
+#endif
 
 static void _auth(xmpp_conn_t * const conn);
 static void _handle_open_tls(xmpp_conn_t * const conn);
@@ -65,7 +90,6 @@ static int _handle_missing_session(xmpp_conn_t * const conn,
 				   void * const userdata);
 
 /* stream:error handler */
-
 static int _handle_error(xmpp_conn_t * const conn,
 			 xmpp_stanza_t * const stanza,
 			 void * const userdata)
@@ -160,7 +184,6 @@ static int _handle_error(xmpp_conn_t * const conn,
 }
 
 /* stream:features handlers */
-
 static int _handle_missing_features(xmpp_conn_t * const conn,
 				    void * const userdata)
 {
@@ -466,7 +489,8 @@ static xmpp_stanza_t *_make_sasl_auth(xmpp_conn_t * const conn,
 /* authenticate the connection 
  * this may get called multiple times.  if any auth method fails, 
  * this will get called again until one auth method succeeds or every
- * method fails */
+ * method fails 
+ */
 static void _auth(xmpp_conn_t * const conn)
 {
     xmpp_stanza_t *auth, *authdata, *query, *child, *iq;
@@ -503,8 +527,7 @@ static void _auth(xmpp_conn_t * const conn)
 
 	/* TLS was tried, unset flag */
 	conn->tls_support = 0;
-    }
-    else if (conn->sasl_support & SASL_MASK_DIGESTMD5) {
+    } else if (conn->sasl_support & SASL_MASK_DIGESTMD5) {
 	auth = _make_sasl_auth(conn, "DIGEST-MD5");
 	if (!auth) {
 	    disconnect_mem_error(conn);
@@ -661,7 +684,15 @@ static void _auth(xmpp_conn_t * const conn)
 }
 
 
-/* this is called on initial stream open */
+/** Set up handlers at stream start.
+ *  This function is called internally to Strophe for handling the opening
+ *  of an XMPP stream.  It's called by the parser when a stream is opened
+ *  or reset, and adds the initial handlers for <stream:error/> and 
+ *  <stream:features/>.  This function is not intended for use outside
+ *  of Strophe.
+ *
+ *  @param conn a Strophe connection object
+ */
 void auth_handle_open(xmpp_conn_t * const conn)
 {
     /* reset all timed handlers */
diff --git a/src/conn.c b/src/conn.c
index 4823b57..3e0605c 100644
--- a/src/conn.c
+++ b/src/conn.c
@@ -12,6 +12,13 @@
 **  distribution.
 */
 
+/** @file 
+ *  Connection management.
+ */
+
+/** @defgroup Connections Connection management
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -20,14 +27,38 @@
 #include "common.h"
 #include "util.h"
 
+#ifndef DEFAULT_SEND_QUEUE_MAX
+/** @def DEFAULT_SEND_QUEUE_MAX
+ *  The default maximum send queue size.  This is currently unused.
+ */
 #define DEFAULT_SEND_QUEUE_MAX 64
+#endif
+#ifndef DISCONNECT_TIMEOUT
+/** @def DISCONNECT_TIMEOUT 
+ *  The time to wait (in milliseconds) for graceful disconnection to
+ *  complete before the connection is reset.  The default is 2 seconds.
+ */
 #define DISCONNECT_TIMEOUT 2000 /* 2 seconds */
+#endif
+#ifndef CONNECT_TIMEOUT
+/** @def CONNECT_TIMEOUT
+ *  The time to wait (in milliseconds) for a connection attempt to succeed 
+ * or error.  The default is 5 seconds.
+ */
 #define CONNECT_TIMEOUT 5000 /* 5 seconds */
+#endif
 
 static int _disconnect_cleanup(xmpp_conn_t * const conn, 
 			       void * const userdata);
 
-
+/** Create a new Strophe connection object.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @return a Strophe connection object or NULL on an error
+ *
+ *  @ingroup Connections
+ */
 xmpp_conn_t *xmpp_conn_new(xmpp_ctx_t * const ctx)
 {
     xmpp_conn_t *conn = NULL;
@@ -111,12 +142,31 @@ xmpp_conn_t *xmpp_conn_new(xmpp_ctx_t * const ctx)
     return conn;
 }
 
+/** Clone a Strophe connection object.
+ *  
+ *  @param conn a Strophe connection object
+ *
+ *  @return the same conn object passed in with its reference count
+ *      incremented by 1
+ *
+ *  @ingroup Connections
+ */
 xmpp_conn_t *xmpp_conn_clone(xmpp_conn_t * const conn)
 {
     conn->ref++;
     return conn;
 }
 
+/** Release a Strophe connection object.
+ *  Decrement the reference count by one for a connection, freeing the 
+ *  connection object if the count reaches 0.
+ *
+ *  @param conn a Strophe connection object
+ *
+ *  @return TRUE if the connection object was freed and FALSE otherwise
+ *
+ *  @ingroup Connections
+ */
 int xmpp_conn_release(xmpp_conn_t * const conn)
 {
     xmpp_ctx_t *ctx;
@@ -212,14 +262,28 @@ int xmpp_conn_release(xmpp_conn_t * const conn)
     return released;
 }
 
+/** Get the JID which is or will be bound to the connection.
+ *  
+ *  @param conn a Strophe connection object
+ *
+ *  @return a string containing the full JID or NULL if it has not been set
+ *
+ *  @ingroup Connections
+ */
 const char *xmpp_conn_get_jid(const xmpp_conn_t * const conn)
 {
     return conn->jid;
 }
 
-/* set the jid of the user or the component name.  in the first case,
- * this can be a full jid, or a bare jid.  in the second case, this will
- * probably be a domain only.
+/** Set the JID of the user that will be bound to the connection.
+ *  If any JID was previously set, it will be discarded.  This should not be 
+ *  be used after a connection is bound.  The function will make a copy of
+ *  the JID string.
+ *
+ *  @param conn a Strophe connection object
+ *  @param jid a full or bare JID
+ *
+ *  @ingroup Connections
  */
 void xmpp_conn_set_jid(xmpp_conn_t * const conn, const char * const jid)
 {
@@ -227,17 +291,55 @@ void xmpp_conn_set_jid(xmpp_conn_t * const conn, const char * const jid)
     conn->jid = xmpp_strdup(conn->ctx, jid);
 }
 
+/** Get the password used for authentication of a connection.
+ *
+ *  @param conn a Strophe connection object
+ *
+ *  @return a string containing the password or NULL if it has not been set
+ *
+ *  @ingroup Connections
+ */
 const char *xmpp_conn_get_pass(const xmpp_conn_t * const conn)
 {
     return conn->pass;
 }
 
+/** Set the password used to authenticate the connection.
+ *  If any password was previously set, it will be discarded.  The function
+ *  will make a copy of the password string.
+ * 
+ *  @param conn a Strophe connection object
+ *  @param pass the password
+ *
+ *  @ingroup Connections
+ */
 void xmpp_conn_set_pass(xmpp_conn_t * const conn, const char * const pass)
 {
     if (conn->pass) xmpp_free(conn->ctx, conn->pass);
     conn->pass = xmpp_strdup(conn->ctx, pass);
 }
 
+/** Initiate a connection to the XMPP server.
+ *  This function returns immediately after starting the connection
+ *  process to the XMPP server, and notifiations of connection state changes
+ *  will be sent to the callback function.  The domain and port to connect to
+ *  are usually determined by an SRV lookup for the xmpp-client service at
+ *  the domain specified in the JID.  If SRV lookup fails, altdomain and 
+ *  altport will be used instead if specified.
+ *
+ *  @param conn a Strophe connection object
+ *  @param domain a string with the domain name to connect to.  If this is
+ *      NULL then the domain is taken from the JID.
+ *  @param altdomain a string with domain to use if SRV lookup fails
+ *  @param altport an integer port number to use if SRV lookup fails
+ *  @param callback a xmpp_conn_handler callback function that will receive
+ *      notifications of connection status
+ *  @param userdata an opaque data pointer that will be passed to the callback
+ *
+ *  @return 0 on success and -1 on an error
+ *
+ *  @ingroup Connections
+ */
 int xmpp_connect_client(xmpp_conn_t * const conn, 
 			  const char * const domain,
 			  const char * const altdomain,
@@ -284,9 +386,12 @@ int xmpp_connect_client(xmpp_conn_t * const conn,
     return 0;
 }
 
-/* this function is only called by the end tag handler.  it is
- * the only place where a conn_disconnect would be called during a clean
- * disconnect sequence */
+/** Cleanly disconnect the connection.
+ *  This function is only called by the stream parser when </stream:stream>
+ *  is received, and it not intended to be called by code outside of Strophe.
+ *
+ *  @param conn a Strophe connection object
+ */
 void conn_disconnect_clean(xmpp_conn_t * const conn)
 {
     /* remove the timed handler */
@@ -295,6 +400,12 @@ void conn_disconnect_clean(xmpp_conn_t * const conn)
     conn_disconnect(conn);
 }
 
+/** Disconnect from the XMPP server.
+ *  This function immediately disconnects from the XMPP server, and should
+ *  not be used outside of the Strophe library.
+ *
+ *  @param conn a Strophe connection object
+ */
 void conn_disconnect(xmpp_conn_t * const conn) 
 {
     xmpp_debug(conn->ctx, "xmpp", "Closing socket.");
@@ -323,9 +434,15 @@ static int _disconnect_cleanup(xmpp_conn_t * const conn,
     return 0;
 }
 
-/* terminates the XMPP stream, closing the underlying socket,
- * and calls the conn_handler.  this function returns immediately
- * without calling the handler if the connection is not active */
+/** Initiate termination of the connection to the XMPP server.
+ *  This function starts the disconnection sequence by sending
+ *  </stream:stream> to the XMPP server.  This function will do nothing
+ *  if the connection state is CONNECTING or CONNECTED.
+ *
+ *  @param conn a Strophe connection object
+ *
+ *  @ingroup Connections
+ */
 void xmpp_disconnect(xmpp_conn_t * const conn)
 {
     if (conn->state != XMPP_STATE_CONNECTING &&
@@ -340,7 +457,17 @@ void xmpp_disconnect(xmpp_conn_t * const conn)
 		      DISCONNECT_TIMEOUT, NULL);
 }
 
-/* convinience function for sending data to a connection */
+/** Send a raw string to the XMPP server.
+ *  This function is a convenience function to send raw string data to the 
+ *  XMPP server.  It is used by Strophe to send short messages instead of
+ *  building up an XML stanza with DOM methods.  This should be used with care
+ *  as it does not validate the data; invalid data may result in immediate
+ *  stream termination by the XMPP server.
+ *
+ *  @param conn a Strophe connection object
+ *  @param fmt a printf-style format string followed by a variable list of
+ *      arguments to format
+ */
 void xmpp_send_raw_string(xmpp_conn_t * const conn, 
 			  const char * const fmt, ...)
 {
@@ -379,7 +506,16 @@ void xmpp_send_raw_string(xmpp_conn_t * const conn,
     }
 }
 
-/* adds data to the send queue for a connection */
+/** Send raw bytes to the XMPP server.
+ *  This function is a convenience function to send raw bytes to the 
+ *  XMPP server.  It is usedly primarly by xmpp_send_raw_string.  This 
+ *  function should be used with care as it does not validate the bytes and
+ *  invalid data may result in stream termination by the XMPP server.
+ *
+ *  @param conn a Strophe connection object
+ *  @param data a buffer of raw bytes
+ *  @param len the length of the data in the buffer
+ */
 void xmpp_send_raw(xmpp_conn_t * const conn,
 		   const char * const data, const size_t len)
 {
@@ -414,6 +550,15 @@ void xmpp_send_raw(xmpp_conn_t * const conn,
     conn->send_queue_len++;
 }
 
+/** Send an XML stanza to the XMPP server.
+ *  This is the main way to send data to the XMPP server.  The function will
+ *  terminate without action if the connection state is not CONNECTED.
+ *
+ *  @param conn a Strophe connection object
+ *  @param stanza a Strophe stanza object
+ *
+ *  @ingroup Connections
+ */
 void xmpp_send(xmpp_conn_t * const conn,
 	       xmpp_stanza_t * const stanza)
 {
@@ -430,6 +575,12 @@ void xmpp_send(xmpp_conn_t * const conn,
     }
 }
 
+/** Send the opening &lt;stream:stream&gt; tag to the server.
+ *  This function is used by Strophe to begin an XMPP stream.  It should
+ *  not be used outside of the library.
+ *
+ *  @param conn a Strophe connection object
+ */
 void conn_open_stream(xmpp_conn_t * const conn)
 {
     xmpp_send_raw_string(conn, 
diff --git a/src/ctx.c b/src/ctx.c
index f080ca5..f4e4fa6 100644
--- a/src/ctx.c
+++ b/src/ctx.c
@@ -12,6 +12,37 @@
 **  distribution.
 */
 
+/** @file
+ *  Runtime contexts, library initialization and shutdown, and versioning.
+ */
+
+/** @defgroup Context Context objects
+ *  These functions create and manipulate Strophe context objects.
+ *
+ *  In order to support usage in a variety of environments, the
+ *  Strophe library uses a runtime context object.  This object
+ *  contains the information on how to do memory allocation and
+ *  logging.  This allows the user to control how memory is allocated
+ *  and what do to with log messages.
+ *
+ *  These issues do not affect programs in the common case, but many
+ *  environments require special treatment.  Abstracting these into a runtime
+ *  context object makes it easy to use Strophe on embedded platforms.
+ *
+ *  Objects in Strophe are reference counted to ease memory management issues,
+ *  but the context objects are not.
+ */
+
+/** @defgroup Init Initialization, shutdown, and versioning
+ *  These functions initialize and shutdown the library, and also allow
+ *  for API version checking.  Failure to properly call these functions may
+ *  result in strange (and platform dependent) behavior.
+ *
+ *  Specifically, the socket library on Win32 platforms must be initialized
+ *  before use (although this is not the case on POSIX systems).  The TLS 
+ *  subsystem must also seed the random number generator.
+ */
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <stdarg.h>
@@ -21,41 +52,63 @@
 #include "common.h"
 #include "util.h"
 
-/* initialization and shutdown */
-
-void xmpp_initialize(void)
+/** Initialize the Strophe library.
+ *  This function initializes subcomponents of the Strophe library and must
+ *  be called for Strophe to operate correctly.
+ *
+ *  @ingroup Init
+ */
+ void xmpp_initialize(void)
 {
     sock_initialize();
     tls_initialize();
 }
 
+/** Shutdown the Strophe library.
+ *
+ *  @ingroup Init
+ */
 void xmpp_shutdown(void)
 {
-    sock_shutdown();
     tls_shutdown();
+    sock_shutdown();
 }
 
-/** version **/
+/* version information */
 
-/* TODO: update from the build system? */
 #ifndef LIBXMPP_VERSION_MAJOR
+/** @def LIBXMPP_VERSION_MAJOR
+ *  The major version number of Strophe.
+ */
 #define LIBXMPP_VERSION_MAJOR (0)
 #endif
 #ifndef LIBXMPP_VERSION_MINOR
+/** @def LIBXMPP_VERSION_MINOR
+ *  The minor version number of Strophe.
+ */
 #define LIBXMPP_VERSION_MINOR (0)
 #endif
 
+/** Check that Strophe supports a specific API version.
+ *
+ *  @param major the major version number
+ *  @param minor the minor version number
+ *
+ *  @return TRUE if the version is supported and FALSE if unsupported
+ *
+ *  @ingroup Init
+ */
 int xmpp_version_check(int major, int minor)
 {
     return (major == LIBXMPP_VERSION_MAJOR) &&
 	   (minor >= LIBXMPP_VERSION_MINOR);
 }
 
-/** run-time contexts **/
+/* We define the global default allocator, logger, and context here. */
 
-/* define the global default allocator, logger and context here */
-
-/* wrap stdlib routines to deal with userdata pointer */
+/* Wrap stdlib routines malloc, free, and realloc for default memory 
+ * management. 
+ */
 static void *_malloc(const size_t size, void * const userdata)
 {
     return malloc(size);
@@ -71,6 +124,7 @@ static void *_realloc(void *p, const size_t size, void * const userdata)
     return realloc(p, size);
 }
 
+/* default memory function map */
 static xmpp_mem_t xmpp_default_mem = {
     _malloc, /* use the thinly wrapped stdlib routines by default */
     _free,
@@ -78,12 +132,22 @@ static xmpp_mem_t xmpp_default_mem = {
     NULL
 };
 
+/* log levels and names */
 static const char * const _xmpp_log_level_name[4] = {"DEBUG", "INFO", "WARN", "ERROR"};
 static const xmpp_log_level_t _xmpp_default_logger_levels[] = {XMPP_LEVEL_DEBUG,
 							       XMPP_LEVEL_INFO,
 							       XMPP_LEVEL_WARN,
 							       XMPP_LEVEL_ERROR};
 
+/** Log a message.
+ *  The default logger writes to stderr.
+ *
+ *  @param userdata the opaque data used by the default logger.  This contains
+ *      the filter level in the default logger.
+ *  @param level the level to log at
+ *  @param area the area the log message is for
+ *  @param msg the log message
+ */
 void xmpp_default_logger(void * const userdata,
 			 const xmpp_log_level_t level,
 			 const char * const area,
@@ -101,6 +165,17 @@ static const xmpp_log_t _xmpp_default_loggers[] = {
 	{&xmpp_default_logger, (void*)&_xmpp_default_logger_levels[XMPP_LEVEL_ERROR]}
 };
 
+/** Get a default logger with filtering.
+ *  The default logger provides a basic logging setup which writes log
+ *  messages to stderr.  Only messages where level is greater than or
+ *  equal to the filter level will be logged.
+ *
+ *  @param level the highest level the logger will log at
+ *
+ *  @return the log structure for the given level
+ *
+ *  @ingroup Context
+ */
 xmpp_log_t *xmpp_get_default_logger(xmpp_log_level_t level)
 {
     /* clamp to the known range */
@@ -112,28 +187,60 @@ xmpp_log_t *xmpp_get_default_logger(xmpp_log_level_t level)
 
 static xmpp_log_t xmpp_default_log = { NULL, NULL };
 
-/** convenience functions for accessing the context **/
-
-/* allocator */
+/* convenience functions for accessing the context */
 
+/** Allocate memory in a Strophe context.
+ *  All Strophe functions will use this to allocate memory. 
+ *
+ *  @param ctx a Strophe context object
+ *  @param size the number of bytes to allocate
+ *
+ *  @return a pointer to the allocated memory or NULL on an error
+ */
 void *xmpp_alloc(const xmpp_ctx_t * const ctx, const size_t size)
 {
     return ctx->mem->alloc(size, ctx->mem->userdata);
 }
 
+/** Free memory in a Strophe context.
+ *  All Strophe functions will use this to free allocated memory.
+ *
+ *  @param ctx a Strophe context object
+ *  @param p a pointer referencing memory to be freed
+ */
 void xmpp_free(const xmpp_ctx_t * const ctx, void *p)
 {
     ctx->mem->free(p, ctx->mem->userdata);
 }
 
+/** Reallocate memory in a Strophe context.
+ *  All Strophe functions will use this to reallocate memory.
+ *
+ *  @param ctx a Strophe context object
+ *  @param p a pointer to previously allocated memory
+ *  @param size the new size in bytes to allocate
+ *
+ *  @return a pointer to the reallocated memory or NULL on an error
+ */
 void *xmpp_realloc(const xmpp_ctx_t * const ctx, void *p,
 		   const size_t size)
 {
     return ctx->mem->realloc(p, size, ctx->mem->userdata);
 }
 
-/* logger */
-
+/** Write a log message to the logger.
+ *  Write a log message to the logger for the context for the specified
+ *  level and area.  This function takes a printf-style format string and a
+ *  variable argument list (in va_list) format.  This function is not meant
+ *  to be called directly, but is used via xmpp_error, xmpp_warn, xmpp_info, 
+ *  and xmpp_debug.
+ *
+ *  @param ctx a Strophe context object
+ *  @param level the level at which to log
+ *  @param area the area to log for
+ *  @param fmt a printf-style format string for the message
+ *  @param ap variable argument list supplied for the format string
+ */
 void xmpp_log(const xmpp_ctx_t * const ctx,
 	      const xmpp_log_level_t level,
 	      const char * const area,
@@ -165,6 +272,16 @@ void xmpp_log(const xmpp_ctx_t * const ctx,
         ctx->log->handler(ctx->log->userdata, level, area, buf);
 }
 
+/** Write to the log at the ERROR level.
+ *  This is a convenience function for writing to the log at the
+ *  ERROR level.  It takes a printf-style format string followed by a 
+ *  variable list of arguments for formatting.
+ *
+ *  @param ctx a Strophe context object
+ *  @param area the area to log for
+ *  @param fmt a printf-style format string followed by a variable list of
+ *      arguments to format
+ */
 void xmpp_error(const xmpp_ctx_t * const ctx,
                 const char * const area,
                 const char * const fmt,
@@ -177,6 +294,16 @@ void xmpp_error(const xmpp_ctx_t * const ctx,
     va_end(ap);
 }
 
+/** Write to the log at the WARN level.
+ *  This is a convenience function for writing to the log at the WARN level.
+ *  It takes a printf-style format string followed by a variable list of
+ *  arguments for formatting.
+ *
+ *  @param ctx a Strophe context object
+ *  @param area the area to log for
+ *  @param fmt a printf-style format string followed by a variable list of
+ *      arguments to format
+ */
 void xmpp_warn(const xmpp_ctx_t * const ctx,
                 const char * const area,
                 const char * const fmt,
@@ -189,6 +316,16 @@ void xmpp_warn(const xmpp_ctx_t * const ctx,
     va_end(ap);
 }
 
+/** Write to the log at the INFO level.
+ *  This is a convenience function for writing to the log at the INFO level.
+ *  It takes a printf-style format string followed by a variable list of
+ *  arguments for formatting.
+ *
+ *  @param ctx a Strophe context object
+ *  @param area the area to log for
+ *  @param fmt a printf-style format string followed by a variable list of
+ *      arguments to format
+ */
 void xmpp_info(const xmpp_ctx_t * const ctx,
                 const char * const area,
                 const char * const fmt,
@@ -201,6 +338,16 @@ void xmpp_info(const xmpp_ctx_t * const ctx,
     va_end(ap);
 }
 
+/** Write to the log at the DEBUG level.
+ *  This is a convenience function for writing to the log at the DEBUG level.
+ *  It takes a printf-style format string followed by a variable list of
+ *  arguments for formatting.
+ *
+ *  @param ctx a Strophe context object
+ *  @param area the area to log for
+ *  @param fmt a printf-style format string followed by a variable list of
+ *      arguments to format
+ */
 void xmpp_debug(const xmpp_ctx_t * const ctx,
                 const char * const area,
                 const char * const fmt,
@@ -213,7 +360,20 @@ void xmpp_debug(const xmpp_ctx_t * const ctx,
     va_end(ap);
 }
 
-/** allocate and initialize a new ctx object */
+/** Create and initialize a Strophe context object.
+ *  If mem is NULL, a default allocation setup will be used which
+ *  wraps malloc(), free(), and realloc() from the standard library.
+ *  If log is NULL, a default logger will be used which does no
+ *  logging.  Basic filtered logging to stderr can be done with the
+ *  xmpp_get_default_logger() convenience function.
+ *
+ *  @param mem a pointer to an xmpp_mem_t structure or NULL
+ *  @param log a pointer to an xmpp_log_t structure or NULL
+ *
+ *  @return the allocated Strophe context object or NULL on an error
+ *
+ *  @ingroup Context
+ */
 xmpp_ctx_t *xmpp_ctx_new(const xmpp_mem_t * const mem, 
 			 const xmpp_log_t * const log)
 {
@@ -242,7 +402,12 @@ xmpp_ctx_t *xmpp_ctx_new(const xmpp_mem_t * const mem,
     return ctx;
 }
 
-/** free a ctx object no longer in use */
+/** Free a Strophe context object that is no longer in use.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @ingroup Context
+ */
 void xmpp_ctx_free(xmpp_ctx_t * const ctx)
 {
     /* mem and log are owned by their suppliers */
diff --git a/src/event.c b/src/event.c
index 37a5f55..1daa098 100644
--- a/src/event.c
+++ b/src/event.c
@@ -12,6 +12,27 @@
 **  distribution.
 */
 
+/** @file
+ *  Event loop and management.
+ */
+
+/** @defgroup EventLoop Event loop
+ *  These functions manage the Strophe event loop.  
+ *  
+ *  Simple tools can use xmpp_run() and xmpp_stop() to manage the life
+ *  cycle of the program.  A common idiom is to set up a few initial
+ *  event handers, call xmpp_run(), and then respond and react to
+ *  events as they come in.  At some point, one of the handlers will
+ *  call xmpp_stop() to quit the event loop which leads to the program
+ *  terminating.
+ * 
+ *  More complex programs will have their own event loops, and should
+ *  ensure that xmpp_run_once() is called regularly from there.  For
+ *  example, a GUI program will already include an event loop to
+ *  process UI events from users, and xmpp_run_once() would be called
+ *  from an idle function.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -29,10 +50,27 @@
 #include "strophe.h"
 #include "common.h"
 
+#ifndef DEFAULT_TIMEOUT
+/** @def DEFAULT_TIMEOUT
+ *  The default timeout in milliseconds for the event loop.
+ *  This is set to 1 millisecond.
+ */
 #define DEFAULT_TIMEOUT 1
+#endif
 
-/* send data and check all connections for their events 
- * and call event handlers.  timeout is in milliseconds */
+/** Run the event loop once.
+ *  This function will run send any data that has been queued by
+ *  xmpp_send and related functions and run through the Strophe even
+ *  loop a single time, and will not wait more than timeout
+ *  milliseconds for events.  This is provided to support integration
+ *  with event loops outside the library, and if used, should be
+ *  called regularly to achieve low latency event handling.
+ *
+ *  @param ctx a Strophe context object
+ *  @param timeout time to wait for events in milliseconds
+ *
+ *  @ingroup EventLoop
+ */
 void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout)
 {
     xmpp_connlist_t *connitem;
@@ -71,6 +109,7 @@ void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout)
 	    }
 	}
 
+	/* write all data from the send queue to the socket */
 	sq = conn->send_queue_head;
 	while (sq) {
 	    towrite = sq->len - sq->written;
@@ -265,6 +304,14 @@ void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout)
     handler_fire_timed(ctx);
 }
 
+/** Start the event loop.
+ *  This function continuously calls xmpp_run_once and does not return
+ *  until xmpp_stop has been called.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @ingroup EventLoop
+ */
 void xmpp_run(xmpp_ctx_t *ctx)
 {
     if (ctx->loop_status != XMPP_LOOP_NOTSTARTED) return;
@@ -277,6 +324,14 @@ void xmpp_run(xmpp_ctx_t *ctx)
     xmpp_debug(ctx, "event", "Event loop completed.");
 }
 
+/** Stop the event loop.
+ *  This will stop the event loop after the current iteration and cause
+ *  xmpp_run to exit.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @ingroup EventLoop
+ */
 void xmpp_stop(xmpp_ctx_t *ctx)
 {
     xmpp_debug(ctx, "event", "Stopping event loop.");
diff --git a/src/handler.c b/src/handler.c
index 6fde3bc..c1f0ce3 100644
--- a/src/handler.c
+++ b/src/handler.c
@@ -12,6 +12,13 @@
 **  distribution.
 */
 
+/** @file
+ *  Event handler management.
+ */
+
+/** @defgroup Handlers Stanza and timed event handlers
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -25,6 +32,13 @@
 #include "strophe.h"
 #include "common.h"
 
+/** Fire off all stanza handlers that match.
+ *  This function is called internally by the event loop whenever stanzas
+ *  are received from the XMPP server.
+ *
+ *  @param conn a Strophe connection object
+ *  @param stanza a Strophe stanza object
+ */
 void handler_fire_stanza(xmpp_conn_t * const conn,
 			 xmpp_stanza_t * const stanza)
 {
@@ -108,8 +122,13 @@ void handler_fire_stanza(xmpp_conn_t * const conn,
     }
 }
 
-/* helper function to fire timed handlers.  returns the 
- * time until the next handler would be fired */
+/** Fire off all timed handlers that are ready.
+ *  This function is called internally by the event loop.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @return the time in milliseconds until the next handler will be ready
+ */
 uint64_t handler_fire_timed(xmpp_ctx_t * const ctx)
 {
     xmpp_connlist_t *connitem;
@@ -169,8 +188,12 @@ uint64_t handler_fire_timed(xmpp_ctx_t * const ctx)
     return min;
 }
 
-/* reset timed handlers for a connection.  this is called
- * whenever connection is successful */
+/** Reset all timed handlers.
+ *  This function is called internally when a connection is successful.
+ *
+ *  @param conn a Strophe connection object
+ *  @param user_only whether to reset all handlers or only user ones
+ */
 void handler_reset_timed(xmpp_conn_t *conn, int user_only)
 {
     xmpp_handlist_t *handitem;
@@ -223,6 +246,13 @@ static void _timed_handler_add(xmpp_conn_t * const conn,
     }
 }
 
+/** Delete a timed handler.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler function pointer to the handler
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_timed_handler_delete(xmpp_conn_t * const conn,
 			       xmpp_timed_handler handler)
 {
@@ -292,6 +322,14 @@ static void _id_handler_add(xmpp_conn_t * const conn,
     }
 }
 
+/** Delete an id based stanza handler.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *  @param id a string containing the id the handler is for
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_id_handler_delete(xmpp_conn_t * const conn,
 			    xmpp_handler handler,
 			    const char * const id)
@@ -322,6 +360,7 @@ void xmpp_id_handler_delete(xmpp_conn_t * const conn,
     }
 }
 
+/* add a stanza handler */
 static void _handler_add(xmpp_conn_t * const conn,
 			 xmpp_handler handler,
 			 const char * const ns,
@@ -386,6 +425,13 @@ static void _handler_add(xmpp_conn_t * const conn,
     }
 }
 
+/** Delete a stanza handler.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_handler_delete(xmpp_conn_t * const conn,
 			 xmpp_handler handler)
 {
@@ -416,6 +462,19 @@ void xmpp_handler_delete(xmpp_conn_t * const conn,
     }
 }
 
+/** Add a timed handler.
+ *  The handler will fire for the first time once the period has elapsed,
+ *  and continue firing regularly after that.  Strophe will try its best
+ *  to fire handlers as close to the period times as it can, but accuracy
+ *  will vary depending on the resolution of the event loop.
+ *   
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a timed handler
+ *  @param period the time in milliseconds between firings
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_timed_handler_add(xmpp_conn_t * const conn,
 			    xmpp_timed_handler handler,
 			    const unsigned long period,
@@ -424,6 +483,15 @@ void xmpp_timed_handler_add(xmpp_conn_t * const conn,
     _timed_handler_add(conn, handler, period, userdata, 1);
 }
 
+/** Add a timed system handler.
+ *  This function is used to add internal timed handlers and should not be
+ *  used outside of the library.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a timed handler
+ *  @param period the time in milliseconds between firings
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ */
 void handler_add_timed(xmpp_conn_t * const conn,
 		       xmpp_timed_handler handler,
 		       const unsigned long period,
@@ -432,6 +500,19 @@ void handler_add_timed(xmpp_conn_t * const conn,
     _timed_handler_add(conn, handler, period, userdata, 0);
 }
 
+/** Add an id based stanza handler.
+
+ *  This function adds a stanza handler for an &lt;iq/&gt; stanza of
+ *  type 'result' or 'error' with a specific id attribute.  This can
+ *  be used to handle responses to specific &lt;iq/&gt;s.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *  @param id a string with the id
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_id_handler_add(xmpp_conn_t * const conn,
 			 xmpp_handler handler,
 			 const char * const id,
@@ -440,6 +521,15 @@ void xmpp_id_handler_add(xmpp_conn_t * const conn,
     _id_handler_add(conn, handler, id, userdata, 1);
 }
 
+/** Add an id based system stanza handler.
+ *  This function is used to add internal id based stanza handlers and should
+ *  not be used outside of the library.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *  @param id a string with the id
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ */
 void handler_add_id(xmpp_conn_t * const conn,
 		    xmpp_handler handler,
 		    const char * const id,
@@ -448,6 +538,25 @@ void handler_add_id(xmpp_conn_t * const conn,
     _id_handler_add(conn, handler, id, userdata, 0);
 }
 
+/** Add a stanza handler.
+ *  This function is used to add a stanza handler to a connection.
+ *  The handler will be called when the any of the filters match.  The
+ *  name filter matches to the top level stanza name.  The type filter
+ *  matches the 'type' attribute of the top level stanza.  The ns
+ *  filter matches the namespace ('xmlns' attribute) of either the top
+ *  level stanza or any of it's immediate children (this allows you do
+ *  handle specific &lt;iq/&gt; stanzas based on the &lt;query/&gt;
+ *  child namespace.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *  @param ns a string with the namespace to match
+ *  @param name a string with the stanza name to match
+ *  @param type a string with the 'type' attribute to match
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ *
+ *  @ingroup Handlers
+ */
 void xmpp_handler_add(xmpp_conn_t * const conn,
 		      xmpp_handler handler,
 		      const char * const ns,
@@ -458,6 +567,17 @@ void xmpp_handler_add(xmpp_conn_t * const conn,
     _handler_add(conn, handler, ns, name, type, userdata, 1);
 }
 
+/** Add a system stanza handler.
+ *  This function is used to add internal stanza handlers and should
+ *  not be used outside of the library.
+ *
+ *  @param conn a Strophe connection object
+ *  @param handler a function pointer to a stanza handler
+ *  @param ns a string with the namespace to match
+ *  @param name a string with the stanza name to match
+ *  @param type a string with the 'type' attribute value to match
+ *  @param userdata an opaque data pointer that will be passed to the handler
+ */
 void handler_add(xmpp_conn_t * const conn,
 		 xmpp_handler handler,
 		 const char * const ns,
diff --git a/src/hash.c b/src/hash.c
index 58269e7..8d95e71 100644
--- a/src/hash.c
+++ b/src/hash.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  Hash tables.
+ */
+
 #include <stdlib.h>
 #include <string.h>
 
diff --git a/src/jid.c b/src/jid.c
index 8f6b437..4e87e58 100644
--- a/src/jid.c
+++ b/src/jid.c
@@ -12,12 +12,25 @@
 **  distribution.
 */
 
+/** @file
+ *  JID creation and parsing.
+ */
+
 #include <string.h>
 
 #include "strophe.h"
 #include "common.h"
 
-/** join jid component parts to form a new jid string */
+/** Create a JID string from component parts node, domain, and resource.
+ *
+ *  @param ctx the Strophe context object
+ *  @param node a string representing the node
+ *  @param domain a string representing the domain.  Required.
+ *  @param resource a string representing the resource
+ *
+ *  @return an allocated string with the full JID or NULL if no domain
+ *      is specified
+ */
 char *xmpp_jid_new(xmpp_ctx_t *ctx, const char *node,
 				    const char *domain,
 				    const char *resource)
@@ -52,7 +65,13 @@ char *xmpp_jid_new(xmpp_ctx_t *ctx, const char *node,
     return result;
 }
 
-/** return a bare jid */
+/** Create a bare JID from a JID.
+ *  
+ *  @param ctx the Strophe context object
+ *  @param jid the JID
+ *
+ *  @return an allocated string with the bare JID or NULL on an error
+ */
 char *xmpp_jid_bare(xmpp_ctx_t *ctx, const char *jid)
 {
     char *result;
@@ -70,7 +89,14 @@ char *xmpp_jid_bare(xmpp_ctx_t *ctx, const char *jid)
     return result;
 }
 
-/** return the node portion of a jid */
+/** Create a node string from a JID.
+ *  
+ *  @param ctx a Strophe context object
+ *  @param jid the JID
+ *
+ *  @return an allocated string with the node or NULL if no node is found
+ *      or an error occurs
+ */
 char *xmpp_jid_node(xmpp_ctx_t *ctx, const char *jid)
 {
     char *result = NULL;
@@ -88,7 +114,13 @@ char *xmpp_jid_node(xmpp_ctx_t *ctx, const char *jid)
     return result;
 }
 
-/** return the domain portion of a jid */
+/** Create a domain string from a JID.
+ *
+ *  @param ctx the Strophe context object
+ *  @param jid the JID
+ *
+ *  @return an allocated string with the domain or NULL on an error
+ */
 char *xmpp_jid_domain(xmpp_ctx_t *ctx, const char *jid)
 {
     char *result = NULL;
@@ -116,7 +148,14 @@ char *xmpp_jid_domain(xmpp_ctx_t *ctx, const char *jid)
     return result;
 }
 
-/** return the node portion of a jid */
+/** Create a resource string from a JID.
+ *
+ *  @param ctx a Strophe context object
+ *  @param jid the JID
+ *
+ *  @return an allocated string with the resource or NULL if no resource 
+ *      is found or an error occurs
+ */
 char *xmpp_jid_resource(xmpp_ctx_t *ctx, const char *jid)
 {
     char *result = NULL;
diff --git a/src/md5.c b/src/md5.c
index a68323d..c4ac4ac 100644
--- a/src/md5.c
+++ b/src/md5.c
@@ -21,6 +21,10 @@
  * will fill a supplied 16-byte array with the digest.
  */
 
+/** @file
+ *  MD5 hash.
+ */
+
 #include <string.h> /* memcpy(), memset() */
 #include "md5.h"
 
diff --git a/src/parser.c b/src/parser.c
index d42cdfb..55ca56b 100644
--- a/src/parser.c
+++ b/src/parser.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  XML parser handlers.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
diff --git a/src/sasl.c b/src/sasl.c
index 8b9e270..21c503e 100644
--- a/src/sasl.c
+++ b/src/sasl.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  SASL authentication.
+ */
+
 #include <string.h>
 
 #include "strophe.h"
diff --git a/src/sha1.c b/src/sha1.c
index f2dcc03..ec4cb6c 100644
--- a/src/sha1.c
+++ b/src/sha1.c
@@ -1,3 +1,7 @@
+/** @file
+ *  SHA-1 hash.
+ */
+
 /*
 SHA-1 in C
 By Steve Reid <sreid@sea-to-sky.net>
diff --git a/src/snprintf.c b/src/snprintf.c
index 48021b3..bd1cdc3 100644
--- a/src/snprintf.c
+++ b/src/snprintf.c
@@ -55,6 +55,10 @@
  *
  **************************************************************/
 
+/** @file
+ *  A snprintf implementation.
+ */
+
 /* JAM: we don't need this - #include "config.h" */
 
 /* JAM: changed declarations to xmpp_snprintf and xmpp_vsnprintf to
diff --git a/src/sock.c b/src/sock.c
index 7044f3d..818cd8d 100644
--- a/src/sock.c
+++ b/src/sock.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  Socket abstraction.
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <sys/types.h>
diff --git a/src/stanza.c b/src/stanza.c
index 4745c61..6e01849 100644
--- a/src/stanza.c
+++ b/src/stanza.c
@@ -12,6 +12,13 @@
 **  distribution.
 */
 
+/** @file
+ *  XMPP stanza creation and manipulation.
+ */
+
+/** @defgroup Stanza Stanza creation and manipulation
+ */
+
 #include <stdio.h>
 #include <string.h>
 
@@ -23,7 +30,17 @@
 #define inline __inline
 #endif
 
-/* allocate an initialize a blank stanza */
+/** Create a stanza object.
+ *  This function allocates and initializes and blank stanza object.
+ *  The stanza will have a reference count of one, so the caller does not
+ *  need to clone it.
+ *
+ *  @param ctx a Strophe context object
+ *
+ *  @return a stanza object
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_new(xmpp_ctx_t *ctx)
 {
     xmpp_stanza_t *stanza;
@@ -44,7 +61,16 @@ xmpp_stanza_t *xmpp_stanza_new(xmpp_ctx_t *ctx)
     return stanza; 
 }
 
-/* clone a stanza */
+/** Clone a stanza object.
+ *  This function increments the reference count of the stanza and all its 
+ *  children.
+ *  
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return the stanza object with it's reference count incremented
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_clone(xmpp_stanza_t * const stanza)
 {
     xmpp_stanza_t *child;
@@ -58,11 +84,18 @@ xmpp_stanza_t *xmpp_stanza_clone(xmpp_stanza_t * const stanza)
     return stanza;
 }
 
-/* copies and stanza and all children
- * this function returns a new stanza copied from stanza.  the new
- * stanza will have no parent and no siblings.  the caller is given
- * a reference to this new stanza.  this function is used to extract
- * a child from one stanza for inclusion in another. */
+/** Copy a stanza and its children.
+ *  This function copies a stanza along with all its children and returns
+ *  the new stanza and children with a reference count of 1.  The returned
+ *  stanza will have no parent and no siblings.  This function is useful
+ *  for extracting a child stanza for inclusion in another tree.
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return a new Strophe stanza object
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_copy(const xmpp_stanza_t * const stanza)
 {
     xmpp_stanza_t *copy, *child, *copychild, *tail;
@@ -118,7 +151,16 @@ copy_error:
     return NULL;
 }
 
-/* free a stanza object and it's contents */
+/** Release a stanza object and all of its children.
+ *  This function releases a stanza object and all of its children, which may
+ *  cause the object to be freed.
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return TRUE if the object was freed and FALSE otherwise
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_release(xmpp_stanza_t * const stanza)
 {
     int released = 0;
@@ -240,12 +282,20 @@ static int _render_stanza_recursive(xmpp_stanza_t *stanza,
     return written;
 }
 
-/* render a stanza to text 
- * a buffer is allocated big enough to hold the stanza 
- * and *buf = buffer.  the size of buffer filled with data
- * is returned in *buflen (does not include trailing \0).  
- * the returned buffer contains a trailing \0 so the result is
- * a valid string.
+/** Render a stanza object to text.
+ *  This function renders a given stanza object, along with its
+ *  children, to text.  The text is returned in an allocated,
+ *  null-terminated buffer.  It starts by allocating a 1024 byte buffer
+ *  and reallocates more memory if that is not large enough.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param buf a reference to a string pointer
+ *  @param buflen a reference to a size_t
+ *
+ *  @return 0 on success (XMPP_EOK), and a number less than 0 on failure
+ *      (XMPP_EMEM, XMPP_EINVOP)
+ *
+ *  @ingroup Stanza
  */
 int  xmpp_stanza_to_text(xmpp_stanza_t *stanza,
 			 char ** const buf,
@@ -290,6 +340,16 @@ int  xmpp_stanza_to_text(xmpp_stanza_t *stanza,
     return XMPP_EOK;
 }
 
+/** Set the name of a stanza.
+ *  
+ *  @param stanza a Strophe stanza object
+ *  @param name a string with the name of the stanza
+ *
+ *  @return XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM,
+ *      XMPP_EINVOP)
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_name(xmpp_stanza_t *stanza, 
 			 const char * const name)
 {
@@ -303,14 +363,37 @@ int xmpp_stanza_set_name(xmpp_stanza_t *stanza,
     return XMPP_EOK;
 }
 
+/** Get the stanza name.
+ *  This function returns a pointer to the stanza name.  If the caller needs
+ *  to store this data, it must make a copy.
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return a string with the stanza name
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_name(xmpp_stanza_t * const stanza)
 {
     if (stanza->type == XMPP_STANZA_TEXT) return NULL;
     return stanza->data;
 }
 
-/* convinience function to copy attributes from the xml parser
- * callback into a stanza.  this replaces all previous attributes */
+/** Set or replace attributes on a stanza.
+ *  This function replaces all previous attributes (if any) with the
+ *  attributes given.  It is used primarily by the XML parser during
+ *  stanza creation.  All strings in the array are copied before placing them
+ *  inside the stanza object.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param attr an array of strings with the attributes in the following
+ *      format: attr[i] = attribute name, attr[i+1] = attribute value
+ *
+ *  @return XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM,
+ *      XMPP_EINVOP)
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_attributes(xmpp_stanza_t * const stanza,
 			       const char * const * const attr)
 {
@@ -335,6 +418,14 @@ int xmpp_stanza_set_attributes(xmpp_stanza_t * const stanza,
     return XMPP_EOK;
 }
 
+/** Count the attributes in a stanza object.
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return the number of attributes for the stanza object
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_get_attribute_count(xmpp_stanza_t * const stanza)
 {
     if (stanza->attributes == NULL) {
@@ -344,6 +435,20 @@ int xmpp_stanza_get_attribute_count(xmpp_stanza_t * const stanza)
     return hash_num_keys(stanza->attributes);
 }
 
+/** Get all attributes for a stanza object.
+ *  This function populates the array with attributes from the stanza.  The
+ *  attr array will be in the format:  attr[i] = attribute name, 
+ *  attr[i+1] = attribute value.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param attr the string array to populate
+ *  @param attrlen the size of the array
+ *
+ *  @return the number of slots used in the array, which will be 2 times the 
+ *      number of attributes in the stanza
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_get_attributes(xmpp_stanza_t * const stanza,
 			       const char **attr, int attrlen)
 {
@@ -375,7 +480,16 @@ int xmpp_stanza_get_attributes(xmpp_stanza_t * const stanza,
     return num;
 }
 
-
+/** Set an attribute for a stanza object.
+ *  
+ *  @param stanza a Strophe stanza object
+ *  @param key a string with the attribute name
+ *  @param value a string with the attribute value
+ *
+ *  @return XMPP_EOK (0) on success or a number less than 0 on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_attribute(xmpp_stanza_t * const stanza,
 			      const char * const key,
 			      const char * const value)
@@ -397,12 +511,34 @@ int xmpp_stanza_set_attribute(xmpp_stanza_t * const stanza,
     return XMPP_EOK;
 }
 
+/** Set the stanza namespace.
+ *  This is a convenience function equivalent to calling:
+ *  xmpp_stanza_set_attribute(stanza, "xmlns", ns);
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param ns a string with the namespace
+ *
+ *  @return XMPP_EOK (0) on success or a number less than 0 on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_ns(xmpp_stanza_t * const stanza,
 		       const char * const ns)
 {
     return xmpp_stanza_set_attribute(stanza, "xmlns", ns);
 }
 
+/** Add a child stanza to a stanza object.
+ *  This function clones the child and appends it to the stanza object's
+ *  children.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param child the child stanza object
+ *
+ *  @return XMPP_EOK (0) on success or a number less than 0 on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_add_child(xmpp_stanza_t *stanza, xmpp_stanza_t *child)
 {
     xmpp_stanza_t *s;
@@ -424,6 +560,19 @@ int xmpp_stanza_add_child(xmpp_stanza_t *stanza, xmpp_stanza_t *child)
     return XMPP_EOK;
 }
 
+/** Set the text data for a text stanza.
+ *  This function copies the text given and sets the stanza object's text to
+ *  it.  Attempting to use this function on a stanza that has a name will
+ *  fail with XMPP_EINVOP.  This function takes the text as a null-terminated
+ *  string.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param text a string with the text
+ *
+ *  @return XMPP_EOK (0) on success or a number less than zero on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_text(xmpp_stanza_t *stanza,
 			 const char * const text)
 {
@@ -437,6 +586,20 @@ int xmpp_stanza_set_text(xmpp_stanza_t *stanza,
     return XMPP_EOK;
 }
 
+/** Set the text data for a text stanza.
+ *  This function copies the text given and sets teh stanza object's text to
+ *  it.  Attempting to use this function on a stanza that has a name will
+ *  fail with XMPP_EINVOP.  This function takes the text as buffer and a length
+ *  as opposed to a null-terminated string.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param text a buffer with the text
+ *  @param size the length of the text
+ *
+ *  @return XMPP_EOK (0) on success and a number less than 0 on failure
+ * 
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_text_with_size(xmpp_stanza_t *stanza,
 				   const char * const text,
 				   const size_t size)
@@ -455,6 +618,16 @@ int xmpp_stanza_set_text_with_size(xmpp_stanza_t *stanza,
     return XMPP_EOK;
 }
 
+/** Get the 'id' attribute of the stanza object.
+ *  This is a convenience function equivalent to:
+ *  xmpp_stanza_get_attribute(stanza, "id");
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return a string with the 'id' attribute value
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_id(xmpp_stanza_t * const stanza)
 {
     if (stanza->type != XMPP_STANZA_TAG)
@@ -466,6 +639,16 @@ char *xmpp_stanza_get_id(xmpp_stanza_t * const stanza)
     return (char *)hash_get(stanza->attributes, "id");
 }
 
+/** Get the namespace attribute of the stanza object.
+ *  This is a convenience function equivalent to:
+ *  xmpp_stanza_get_attribute(stanza, "xmlns");
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return a string with the 'xmlns' attribute value
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_ns(xmpp_stanza_t * const stanza)
 {
     if (stanza->type != XMPP_STANZA_TAG)
@@ -477,6 +660,16 @@ char *xmpp_stanza_get_ns(xmpp_stanza_t * const stanza)
     return (char *)hash_get(stanza->attributes, "xmlns");
 }
 
+/** Get the 'type' attribute of the stanza object.
+ *  This is a convenience function equivalent to:
+ *  xmpp_stanza_get_attribute(stanza, "type");
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return a string with the 'type' attribute value
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_type(xmpp_stanza_t * const stanza)
 {
     if (stanza->type != XMPP_STANZA_TAG)
@@ -488,6 +681,17 @@ char *xmpp_stanza_get_type(xmpp_stanza_t * const stanza)
     return (char *)hash_get(stanza->attributes, "type");
 }
 
+/** Get the first child of stanza with name.
+ *  This function searches all the immediate children of stanza for a child
+ *  stanza that matches the name.  The first matching child is returned.
+ *  
+ *  @param stanza a Strophe stanza object
+ *  @param name a string with the name to match
+ *
+ *  @return the matching child stanza object or NULL if no match was found
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_get_child_by_name(xmpp_stanza_t * const stanza, 
 					     const char * const name)
 {
@@ -502,16 +706,46 @@ xmpp_stanza_t *xmpp_stanza_get_child_by_name(xmpp_stanza_t * const stanza,
     return child;
 }
 
+/** Get the list of children.
+ *  This function returns the first child of the stanza object.  The rest
+ *  of the children can be obtained by calling xmpp_stanza_get_next() to
+ *  iterate over the siblings.
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return the first child stanza or NULL if there are no children
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_get_children(xmpp_stanza_t * const stanza) 
 {
     return stanza->children;
 }
 
+/** Get the next sibling of a stanza.
+ *  
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return the next sibling stanza or NULL if there are no more siblings
+ *
+ *  @ingroup Stanza
+ */
 xmpp_stanza_t *xmpp_stanza_get_next(xmpp_stanza_t * const stanza)
 {
     return stanza->next;
 }
 
+/** Get the text data for a text stanza.
+ *  This function copies the text data from a stanza and returns the new
+ *  allocated string.  The caller is responsible for freeing this string
+ *  with xmpp_free().
+ *
+ *  @param stanza a Strophe stanza object
+ *
+ *  @return an allocated string with the text data
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_text(xmpp_stanza_t * const stanza)
 {
     size_t len, clen;
@@ -539,18 +773,52 @@ char *xmpp_stanza_get_text(xmpp_stanza_t * const stanza)
     return text;
 }
 
+/** Set the 'id' attribute of a stanza.
+ *
+ *  This is a convenience function for:
+ *  xmpp_stanza_set_attribute(stanza, 'id', id);
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param id a string containing the 'id' value
+ *
+ *  @return XMPP_EOK (0) on success or a number less than 0 on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_id(xmpp_stanza_t * const stanza,
 		       const char * const id)
 {
     return xmpp_stanza_set_attribute(stanza, "id", id);
 }
 
+/** Set the 'type' attribute of a stanza.
+ *  This is a convenience function for:
+ *  xmpp_stanza_set_attribute(stanza, 'type', type);
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param type a string containing the 'type' value
+ *
+ *  @return XMPP_EOK (0) on success or a number less than 0 on failure
+ *
+ *  @ingroup Stanza
+ */
 int xmpp_stanza_set_type(xmpp_stanza_t * const stanza,
 			 const char * const type)
 {
     return xmpp_stanza_set_attribute(stanza, "type", type);
 }
 
+/** Get an attribute from a stanza.
+ *  This function returns a pointer to the attribute value.  If the caller
+ *  wishes to save this value it must make its own copy.
+ *
+ *  @param stanza a Strophe stanza object
+ *  @param name a string containing attribute name
+ *
+ *  @return a string with the attribute value or NULL on an error
+ *
+ *  @ingroup Stanza
+ */
 char *xmpp_stanza_get_attribute(xmpp_stanza_t * const stanza,
 				const char * const name)
 {
diff --git a/src/thread.c b/src/thread.c
index 8ee4eaf..167d931 100644
--- a/src/thread.c
+++ b/src/thread.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  Thread absraction.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 
diff --git a/src/tls_dummy.c b/src/tls_dummy.c
index 5ee8087..8859131 100644
--- a/src/tls_dummy.c
+++ b/src/tls_dummy.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  TLS dummy implementation.
+ */
+
 #include "common.h"
 #include "tls.h"
 #include "sock.h"
diff --git a/src/tls_gnutls.c b/src/tls_gnutls.c
index 8e4ec78..7fc13b5 100644
--- a/src/tls_gnutls.c
+++ b/src/tls_gnutls.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  TLS implementation with GNUTLS
+ */
+
 #include <gnutls/gnutls.h>
 
 #include "common.h"
diff --git a/src/tls_openssl.c b/src/tls_openssl.c
index 6864020..c567fe9 100644
--- a/src/tls_openssl.c
+++ b/src/tls_openssl.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  TLS implementation with OpenSSL.
+ */
+
 #include <openssl/ssl.h>
 #include <openssl/applink.c>
 
diff --git a/src/tls_schannel.c b/src/tls_schannel.c
index 20c1db1..3274c1e 100644
--- a/src/tls_schannel.c
+++ b/src/tls_schannel.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  TLS implementation with Win32 SChannel.
+ */
+
 #include "common.h"
 #include "tls.h"
 #include "sock.h"
diff --git a/src/util.c b/src/util.c
index 469e0e8..c2f2963 100644
--- a/src/util.c
+++ b/src/util.c
@@ -12,6 +12,10 @@
 **  distribution.
 */
 
+/** @file
+ *  Utility functions.
+ */
+
 #include <stdio.h>
 #include <string.h>
 
@@ -28,6 +32,15 @@
 #include "util.h"
 
 /** implement our own strdup that uses the ctx allocator */
+/** Duplicate a string.
+ *  This function replaces the standard strdup library call with a version
+ *  that uses the Strophe context object's allocator.
+ *
+ *  @param ctx a Strophe context object
+ *  @param s a string
+ *
+ *  @return a new allocates string with the same data as s or NULL on error
+ */
 char *xmpp_strdup(const xmpp_ctx_t * const ctx, const char * const s)
 {
     size_t len;
@@ -45,6 +58,13 @@ char *xmpp_strdup(const xmpp_ctx_t * const ctx, const char * const s)
     return copy;
 }
 
+/** Return an integer based time stamp.
+ *  This function uses gettimeofday or timeGetTime (on Win32 platforms) to
+ *  compute an integer based time stamp.  This is used internally by the
+ *  event loop and timed handlers.
+ *
+ *  @return an integer time stamp
+ */
 uint64_t time_stamp(void)
 {
 #ifdef _WIN32
@@ -58,11 +78,28 @@ uint64_t time_stamp(void)
 #endif
 }
 
+/** Get the time elapsed between two time stamps.
+ *  This function returns the time elapsed between t1 and t2 by subtracting
+ *  t1 from t2.  If t2 happened before t1, the result will be negative.  This
+ *  function is used internally by the event loop and timed handlers.
+ *
+ *  @param t1 first time stamp
+ *  @param t2 second time stamp
+ *
+ *  @return number of milliseconds between the stamps
+ */
 uint64_t time_elapsed(uint64_t t1, uint64_t t2)
 {
     return (uint64_t)(t2 - t1);
 }
 
+/** Disconnect the stream with a memory error.
+ *  This is a convenience function used internally by various parts of
+ *  the Strophe library for terminating the connection because of a 
+ *  memory error.
+ *
+ *  @param conn a Strophe connection object
+ */
 void disconnect_mem_error(xmpp_conn_t * const conn)
 {
     xmpp_error(conn->ctx, "xmpp", "Memory allocation error");