# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1742729163 -3600
# Node ID 7bc999fe285dd0fa26d0bd04123198966b48aaaa
# Parent  a12e102ff67fedf273645f06e48bf6842413a9e0
more documentation for buffer.h + set errno in cxBufferSeek() on invalid whence argument

relates to #451

diff -r a12e102ff67f -r 7bc999fe285d docs/Writerside/topics/buffer.h.md
--- a/docs/Writerside/topics/buffer.h.md	Sun Mar 23 11:28:20 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Sun Mar 23 12:26:03 2025 +0100
@@ -54,9 +54,11 @@
 void cxBufferFree(CxBuffer *buffer);
 ```
 
-<warning>
-TODO: document
-</warning>
+The above functions destroy the buffer and deallocate the buffer's memory when the `CX_BUFFER_FREE_CONTENTS` flag is set.
+
+The function `cxBufferDestroy()` is to be used when the buffer was initialized with `cxBufferInit()`,
+and the function `cxBufferFree()` is to be used when the buffer was created with `cxBufferCreate()`.
+The only difference is, that `cxBufferFree()` additionally deallocates the memory of the `CxBuffer` structure. 
 
 ## Write
 
@@ -91,6 +93,8 @@
         CxBuffer *buffer);
 
 int cxBufferGet(CxBuffer *buffer);
+
+bool cxBufferEof(const CxBuffer *buffer);
 ```
 
 <warning>
@@ -117,13 +121,16 @@
 #include <cx/buffer.h>
 
 int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence);
-
-bool cxBufferEof(const CxBuffer *buffer);
 ```
 
-<warning>
-TODO: document
-</warning>
+The function `cxBufferSeek()` is a `fseek()`-like function that sets the current position in the buffer
+relative to the start (when `whence` is `SEEK_SET`), the current position (when `whence` is `SEEK_CUR`),
+or end (when `whence` is `SEEK_END`) of the buffer.
+
+If the resulting position is negative, or larger than the size (i.e. the first unused byte),
+this function returns non-zero and sets `errno` to `EOVERFLOW`.
+
+> Note that the error behavior of `cxBufferSeek()` is not exactly the same as for POSIX `fseek()`.
 
 ## Shift Contents
 
diff -r a12e102ff67f -r 7bc999fe285d src/buffer.c
--- a/src/buffer.c	Sun Mar 23 11:28:20 2025 +0100
+++ b/src/buffer.c	Sun Mar 23 12:26:03 2025 +0100
@@ -139,6 +139,7 @@
             npos = 0;
             break;
         default:
+            errno = EINVAL;
             return -1;
     }