Most public API points are now documented.

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");