diff -r 55adc92e7c09 -r 80609f9675f1 ucx/buffer.h
--- a/ucx/buffer.h	Tue Feb 16 17:39:33 2016 +0100
+++ b/ucx/buffer.h	Mon May 23 12:28:32 2016 +0200
@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2013 Olaf Wintermann. All rights reserved.
+ * Copyright 2015 Olaf Wintermann. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -97,11 +97,11 @@
  * 
  * @param space pointer to the memory area, or <code>NULL</code> to allocate
  * new memory
- * @param size the size of the buffer
+ * @param capacity the capacity of the buffer
  * @param flags buffer features (see UcxBuffer.flags)
  * @return the new buffer
  */
-UcxBuffer *ucx_buffer_new(void *space, size_t size, int flags);
+UcxBuffer *ucx_buffer_new(void *space, size_t capacity, int flags);
 
 /**
  * Destroys a buffer.
@@ -120,10 +120,9 @@
  * 
  * @param src the source buffer
  * @param start the start position of extraction
- * @param length the count of bytes to extract or 0 if all of the remaining
- * bytes shall be extracted
+ * @param length the count of bytes to extract (must not be zero)
  * @param flags feature mask for the new buffer
- * @return 
+ * @return a new buffer containing the extraction
  */
 UcxBuffer* ucx_buffer_extract(UcxBuffer *src,
         size_t start, size_t length, int flags);
@@ -136,7 +135,7 @@
  * @return a new buffer with the extracted content
  */
 #define ucx_buffer_clone(src,flags) \
-    ucx_buffer_extract(src, 0, 0, flags)
+    ucx_buffer_extract(src, 0, (src)->capacity, flags)
 
 /**
  * Moves the position of the buffer.
@@ -145,7 +144,11 @@
  *
  * SEEK_SET marks the start of the buffer.
  * SEEK_CUR marks the current position.
- * SEEK_END marks the first 0-byte in the buffer.
+ * SEEK_END marks the end of the buffer.
+ * 
+ * With an offset of zero, this function sets the buffer position to zero
+ * (SEEK_SET), the buffer size (SEEK_END) or leaves the buffer position
+ * unchanged (SEEK_CUR).
  * 
  * @param buffer
  * @param offset position offset relative to <code>whence</code>
@@ -182,12 +185,12 @@
  * the buffer capacity is doubled, as long as it would not hold the current
  * content plus the additional required bytes.
  * 
- * <b>Attention:</b> the argument provided is the count of <i>additional</i>
- * bytes the buffer shall hold. It is <b>NOT</b> the total count of bytes the
+ * <b>Attention:</b> the argument provided is the number of <i>additional</i>
+ * bytes the buffer shall hold. It is <b>NOT</b> the total number of bytes the
  * buffer shall hold.
  * 
  * @param buffer the buffer to extend
- * @param additional_bytes the count of additional bytes the buffer shall
+ * @param additional_bytes the number of additional bytes the buffer shall
  * <i>at least</i> hold
  * @return 0 on success or a non-zero value on failure
  */
@@ -216,7 +219,7 @@
  * @param size the length of one element
  * @param nitems the element count
  * @param buffer the UcxBuffer to read from
- * @return the total count of bytes read
+ * @return the total number of elements read
  */
 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems,
         UcxBuffer *buffer);