diff -r ec0ae0c8854e -r 151f5345f303 ucx/string.h
--- a/ucx/string.h	Wed Jul 17 16:17:42 2013 +0200
+++ b/ucx/string.h	Wed Jul 17 20:03:01 2013 +0200
@@ -183,12 +183,48 @@
  * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
  * <code>free()</code>.
  * 
+ * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
+ * terminated.
+ * 
  * @param string the string to duplicate
- * @return a duplicate of the argument
+ * @return a duplicate of the string
  */
 sstr_t sstrdup(sstr_t string);
-sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
 
+/**
+ * Creates a duplicate of the specified string using an UcxAllocator.
+ * 
+ * The new sstr_t will contain a copy allocated by the allocators
+ * ucx_allocator_malloc function. So it is implementation depended, whether the
+ * returned sstr_t.ptr pointer must be passed to the allocators
+ * ucx_allocator_free function manually.
+ * 
+ * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
+ * terminated.
+ * 
+ * @param allocator a valid instance of an UcxAllocator
+ * @param string the string to duplicate
+ * @return a duplicate of the string
+ */
+sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
+
+/**
+ * Omits leading and trailing spaces.
+ * 
+ * This function returns a new sstr_t containing a trimmed version of the
+ * specified string.
+ * 
+ * <b>Note:</b> the new sstr_t references the same memory, thus you
+ * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
+ * <code>free()</code>. It is also highly recommended to avoid assignments like
+ * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
+ * source string. Assignments of this type are only permitted, if the
+ * sstr_t.ptr of the source string does not need to be freed or if another
+ * reference to the source string exists.
+ * 
+ * @param string the string that shall be trimmed
+ * @return a new sstr_t containing the trimmed string
+ */
 sstr_t sstrtrim(sstr_t string);
 
 #ifdef	__cplusplus