diff -r 8693d7874773 -r 5a0859739b76 ucx/ucx.h
--- a/ucx/ucx.h	Mon Jul 15 16:59:52 2013 +0200
+++ b/ucx/ucx.h	Wed Jul 17 11:47:02 2013 +0200
@@ -25,6 +25,12 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * Main UCX Header providing most common definitions.
+ * 
+ * @file   ucx.h
+ * @author Olaf Wintermann
+ */
 
 #ifndef UCX_H
 #define	UCX_H
@@ -39,19 +45,81 @@
 extern "C" {
 #endif
 
+/**
+ * Generic loop statement for lists.
+ * 
+ * The first argument is the type of the list and its elements (e.g. UcxList).
+ * The structure invariant of the list must be as follows:
+ * <ul>
+ *   <li>a first (non-<code>NULL</code>) element</li>
+ *   <li>for each element a reference to the <code>next</code> element (the
+ *       variable name of the pointer MUST be <code>next</code>)</li>
+ *   <li>the last element of the list MUST have the <code>next</code> pointer
+ *       set to <code>NULL</code></li>
+ * </ul>
+ * 
+ * The second argument is a pointer to the list. In most cases this will be the
+ * pointer to the first element of the list, but it may also be an arbitrary
+ * element of the list. The iteration will then start with that element.
+ * 
+ * The third argument is the name of the iteration variable. The scope of
+ * this variable is limited to the <code>UCX_FOREACH</code> statement.
+ * 
+ * @param type The type of <b>both</b> the list and the element
+ * @param list The first element of the list
+ * @param elem The variable name of the element
+ */
 #define UCX_FOREACH(type,list,elem) \
         for (type elem = list ; elem != NULL ; elem = elem->next)
 
-/* element1,element2,custom data -> {-1,0,1} */
+/**
+ * Function pointer to a compare function.
+ * 
+ * The compare function shall take three arguments: the two values that shall be
+ * compared and optional additional data.
+ * The function shall then return -1 if the first argument is less than the
+ * second argument, 1 if the first argument is greater than the second argument
+ * and 0 if both arguments are equal. If the third argument is
+ * <code>NULL</code>, it shall be ignored.
+ */
 typedef int(*cmp_func)(void*,void*,void*);
 
-/* element,custom data -> copy of element */
+/**
+ * Function pointer to a copy function.
+ * 
+ * The copy function shall create a copy of the first argument and may use
+ * additional data provided by the second argument. If the second argument is
+ * <code>NULL</code>, it shall be ignored.
+
+ * <b>Attention:</b> if pointers returned by functions of this type may be
+ * passed to <code>free()</code> depends on the implementation of the
+ * respective <code>copy_func</code>.
+ */
 typedef void*(*copy_func)(void*,void*);
 
-/* buffer, element size, element count, stream */
+/**
+ * Function pointer to a write function.
+ * 
+ * The signature of the write function shall be compatible to the signature
+ * of standard <code>fwrite</code>, though it may use arbitrary data types for
+ * source and destination.
+ * 
+ * The arguments shall contain (in ascending order): a pointer to the source,
+ * the length of one element, the element count, a pointer to the destination.
+ */
 typedef size_t(*write_func)(const void*, size_t, size_t, void*);
 
-/* buffer, element size, element count, stream */
+/**
+ * Function pointer to a read function.
+ * 
+ * The signature of the read function shall be compatible to the signature
+ * of standard <code>fread</code>, though it may use arbitrary data types for
+ * source and destination.
+ * 
+ * The arguments shall contain (in ascending order): a pointer to the
+ * destination, the length of one element, the element count, a pointer to the
+ * source.
+ */
 typedef size_t(*read_func)(void*, size_t, size_t, void*);
 
 #ifdef	__cplusplus