# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1742649269 -3600
# Node ID b9a940779877edd0ec1e9451bf471e556b435f07
# Parent  a9d730c8b94a65fc02bd924686afc31c52028e4b
define structure for buffer.h doc

relates to #451

diff -r a9d730c8b94a -r b9a940779877 docs/Writerside/topics/buffer.h.md
--- a/docs/Writerside/topics/buffer.h.md	Fri Mar 21 19:47:38 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Sat Mar 22 14:14:29 2025 +0100
@@ -15,30 +15,154 @@
 to automatically resizing the buffer space.
 Please refer to the API doc for the fields prefixed with `flush_` to learn more. 
 
-<!--
-## Undocumented Symbols (TODO)
-### cxBufferAppend
-### cxBufferClear
-### cxBufferCreate
-### cxBufferDestroy
-### cxBufferEnableFlushing
-### cxBufferEof
-### cxBufferFlush
-### cxBufferFree
-### cxBufferGet
-### cxBufferInit
-### cxBufferMinimumCapacity
-### cxBufferPut
-### cxBufferPutString
-### cxBufferRead
-### cxBufferReset
-### cxBufferSeek
-### cxBufferShift
-### cxBufferShiftLeft
-### cxBufferShiftRight
-### cxBufferTerminate
-### cxBufferWrite
--->
+## Example
+
+<warning>
+TODO: add example
+</warning>
+
+## Create
+
+```C
+#include <cx/buffer.h>
+
+int cxBufferInit(CxBuffer *buffer, void *space, size_t capacity,
+        const CxAllocator *allocator, int flags);
+
+CxBuffer *cxBufferCreate(void *space,size_t capacity,
+        const CxAllocator *allocator, int flags);
+
+// available flags:
+#define CX_BUFFER_DEFAULT
+#define CX_BUFFER_FREE_CONTENTS
+#define CX_BUFFER_AUTO_EXTEND
+#define CX_BUFFER_COPY_ON_WRITE
+#define CX_BUFFER_COPY_ON_EXTEND
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Destroy
+
+```C
+#include <cx/buffer.h>
+
+void cxBufferDestroy(CxBuffer *buffer);
+
+void cxBufferFree(CxBuffer *buffer);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Write
+
+```C
+#include <cx/buffer.h>
+
+size_t cxBufferWrite(const void *ptr, size_t size, size_t nitems,
+        CxBuffer *buffer);
+
+size_t cxBufferAppend(const void *ptr, size_t size, size_t nitems,
+        CxBuffer *buffer);
+
+int cxBufferPut(CxBuffer *buffer, int c);
+
+size_t cxBufferPutString(CxBuffer *buffer, const char *str);
+
+int cxBufferTerminate(CxBuffer *buffer);
+
+int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Read
+
+```C
+#include <cx/buffer.h>
+
+size_t cxBufferRead(void *ptr, size_t size, size_t nitems,
+        CxBuffer *buffer);
+
+int cxBufferGet(CxBuffer *buffer);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Reset and Clear
+
+```C
+#include <cx/buffer.h>
+
+void cxBufferReset(CxBuffer *buffer);
+
+void cxBufferClear(CxBuffer *buffer);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Random Access
+
+```C
+#include <cx/buffer.h>
+
+int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence);
+
+bool cxBufferEof(const CxBuffer *buffer);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Shift Contents
+
+```C
+#include <cx/buffer.h>
+
+int cxBufferShift(CxBuffer *buffer, off_t shift);
+
+int cxBufferShiftRight(CxBuffer *buffer, size_t shift);
+
+int cxBufferShiftLeft(CxBuffer *buffer, size_t shift);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Flushing
+
+```C
+#include <cx/buffer.h>
+
+typedef struct cx_buffer_flush_config_s {
+    size_t threshold;
+    size_t blksize;
+    size_t blkmax;
+    void *target;
+    cx_write_func wfunc;
+} CxBufferFlushConfig;
+
+int cxBufferEnableFlushing(CxBuffer *buffer,
+        CxBufferFlushConfig config);
+
+size_t cxBufferFlush(CxBuffer *buffer);
+```
+
+<warning>
+TODO: document
+</warning>
 
 <seealso>
 <category ref="apidoc">