diff -r 965fd17ed9cf -r 234920008754 ucx/string.h
--- a/ucx/string.h	Wed Jul 17 12:32:03 2013 +0200
+++ b/ucx/string.h	Wed Jul 17 15:56:01 2013 +0200
@@ -25,51 +25,98 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * Bounded string implementation.
+ * 
+ * The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
+ * The main difference to C strings is, that <code>sstr_t</code> does <b>not
+ * need to be <code>NULL</code>-terminated</b>. Instead the length is stored
+ * within the structure.
+ * 
+ * When using <code>sstr_t</code>, developers must be full aware of what type
+ * of string (<code>NULL</code>-terminated) or not) they are using, when 
+ * accessing the <code>char* ptr</code> directly.
+ * 
+ * The UCX string module provides some common string functions, known from
+ * standard libc, working with <code>sstr_t</code>.
+ * 
+ * @file   string.h
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
 
-#ifndef _SSTRING_H
-#define	_SSTRING_H
+#ifndef UCX_STRING_H
+#define	UCX_STRING_H
 
 #include "ucx.h"
 #include "allocator.h"
 #include <stddef.h>
 
-/* use macros for literals only */
-#define S(s) { (char*)s, sizeof(s)-1 }
-#define ST(s) sstrn((char*)s, sizeof(s)-1)
+/** Shortcut for a <code>sstr_t struct</code> literal. */
+#define ST(s) { (char*)s, sizeof(s)-1 }
+/** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
+#define S(s) sstrn((char*)s, sizeof(s)-1)
 
 #ifdef	__cplusplus
 extern "C" {
 #endif
 
-typedef struct sstring {
+/**
+ * The UCX string structure.
+ */
+typedef struct {
+   /** A reference to the string (<b>not necessarily  <code>NULL</code>
+    * -terminated</b>) */
     char   *ptr;
+    /** The length of the string */
     size_t length;
 } sstr_t;
 
-/*
- * creates a new sstr_t from a null terminated string
+/**
+ * Creates a new sstr_t based on a C string.
+ * 
+ * The length is implicitly inferred by using a call to <code>strlen()</code>.
  *
- * s  null terminated string
+ * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
+ * do want a copy, use sstrdup() on the return value of this function.
+ * 
+ * @param cstring the C string to wrap
+ * @return a new sstr_t containing the C string
+ * 
+ * @see sstrn()
  */
-sstr_t sstr(char *s);
+sstr_t sstr(char *cstring);
 
-/*
- * creates a new sstr_t from a string and length
+/**
+ * Creates a new sstr_t of the specified length based on a C string.
  *
- * s  string
- * n  length of string
+ * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
+ * do want a copy, use sstrdup() on the return value of this function.
+ * 
+ * @param cstring  the C string to wrap
+ * @param length   the length of the string
+ * @return a new sstr_t containing the C string
+ * 
+ * @see sstr()
+ * @see S()
  */
-sstr_t sstrn(char *s, size_t n);
+sstr_t sstrn(char *cstring, size_t length);
 
 
-/*
- * gets the length of n sstr_t strings
+/**
+ * Returns the cumulated length of all specified strings.
  *
- * n    number of strings
- * s    string
- * ...  strings
+ * At least one string must be specified.
+ * 
+ * <b>Attention:</b> if the count argument does not match the count of the
+ * specified strings, the behavior is undefined.
+ *
+ * @param count    the total number of specified strings (so at least 1)
+ * @param string   the first string
+ * @param ...      all other strings
+ * @return the cumulated length of all strings
  */
-size_t sstrnlen(size_t n, sstr_t s, ...);
+size_t sstrnlen(size_t count, sstr_t string, ...);
 
 
 /*
@@ -115,10 +162,32 @@
  */
 sstr_t* sstrsplit(sstr_t s, sstr_t d, size_t *n);
 
+/**
+ * Compares two UCX strings with standard <code>memcmp()</code>.
+ * 
+ * At first it compares the sstr_t.length attribute of the two strings. The
+ * <code>memcmp()</code> function is called, if and only if the lengths match.
+ * 
+ * @param s1 the first string
+ * @param s2 the second string
+ * @return -1, if the length of s1 is less than the length of s2 or 1, if the 
+ * length of s1 is greater than the length of s2 or the result of
+ * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
+ */
 int sstrcmp(sstr_t s1, sstr_t s2);
 
-sstr_t sstrdup(sstr_t s);
-sstr_t sstrdup_alloc(UcxAllocator *allocator, sstr_t s);
+/**
+ * Creates a duplicate of the specified string.
+ * 
+ * The new sstr_t will contain a copy allocated by standard
+ * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
+ * <code>free()</code>.
+ * 
+ * @param string the string to duplicate
+ * @return a duplicate of the argument
+ */
+sstr_t sstrdup(sstr_t string);
+sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
 
 sstr_t sstrtrim(sstr_t string);
 
@@ -126,4 +195,4 @@
 }
 #endif
 
-#endif	/* _SSTRING_H */
+#endif	/* UCX_STRING_H */