diff -r d3100c987a39 -r f90a7cfe2480 src/cx/buffer.h
--- a/src/cx/buffer.h	Mon Jul 25 14:16:49 2022 +0200
+++ b/src/cx/buffer.h	Mon Jul 25 15:29:56 2022 +0200
@@ -310,7 +310,20 @@
 /**
  * Writes data to a CxBuffer.
  *
- * The position of the buffer is increased by the number of bytes written.
+ * If flushing is enabled and the buffer needs to flush, the data is flushed to
+ * the target until the target signals that it cannot take more data by
+ * returning zero via the respective write function. In that case, the remaining
+ * data in this buffer is shifted to the beginning of this buffer so that the
+ * newly available space can be used to append as much data as possible. This
+ * function only stops writing more elements, when the flush target and this
+ * buffer are both incapable of taking more data or all data has been written.
+ * The number returned by this function is the total number of elements that
+ * could be written during the process. It does not necessarily mean that those
+ * elements are still in this buffer, because some of them could have also be
+ * flushed already.
+ *
+ * If automatic flushing is not enabled, the position of the buffer is increased
+ * by the number of bytes written.
  *
  * \note The signature is compatible with the fwrite() family of functions.
  *