diff -r 3672b89e606c -r cc60b7d07912 src/cx/buffer.h
--- a/src/cx/buffer.h	Thu Jan 16 18:56:17 2025 +0100
+++ b/src/cx/buffer.h	Thu Jan 16 18:56:44 2025 +0100
@@ -484,14 +484,26 @@
  * 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
+ * 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.
- * If number of items that shall be written is larger than the buffer can hold,
- * the first items from @c ptr are directly relayed to the flush target, if
- * possible.
- * The number returned by this function is only the number of elements from
- * @c ptr that could be written to either the flush target or the buffer.
+ *
+ * If, after flushing, the number of items that shall be written still exceeds
+ * the capacity or flush threshold, this function tries to write all items directly
+ * to the flush target, if possible.
+ *
+ * The number returned by this function is the number of elements from
+ * @c ptr that could be written to either the flush target or the buffer
+ * (so it does not include the number of items that had been already in the buffer
+ * in were flushed during the process).
+ *
+ * @attention
+ * When @p size is larger than one and the contents of the buffer are not aligned
+ * with @p size, flushing stops after all complete items have been flushed, leaving
+ * the mis-aligned part in the buffer.
+ * Afterward, this function refuses to write any data to the buffer, until the
+ * mis-alignment has been resolved (e.g. by manually flushing with cxBufferFlush()).
  *
  * @note The signature is compatible with the fwrite() family of functions.
  *