# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1743096249 -3600
# Node ID 8ff604356af7cc58086c7c01b872115a42dae61e
# Parent  f993745c60f08d10dcf28827daf31bfb3b2d3382
document buffer create/init

relates to #451

diff -r f993745c60f0 -r 8ff604356af7 docs/Writerside/topics/buffer.h.md
--- a/docs/Writerside/topics/buffer.h.md	Wed Mar 26 16:38:08 2025 +0100
+++ b/docs/Writerside/topics/buffer.h.md	Thu Mar 27 18:24:09 2025 +0100
@@ -38,9 +38,17 @@
 #define CX_BUFFER_COPY_ON_EXTEND
 ```
 
-<warning>
-TODO: document
-</warning>
+For creating a UCX buffer you have two options: initialize a pre-allocated structure, or allocate and initialize a new structure in one call.
+
+For the first option, you can call `cxBufferInit()` with the `buffer` argument pointing to an uninitialized `CxBuffer` structure.
+You can pass a pre-allocated `space`, the desired `capacity`, and an `allocator`.
+If `space` is `NULL`, the `allocator` is used to allocate enough space to match the desired `capacity`.
+
+The `flags` argument is a bit-wise-or combination of the constants listed below.
+
+The function `cxBufferCreate()` is equivalent, except that it uses the `allocator` to allocate a new `CxBuffer` structure, instead of initializing an existing one.
+
+If any allocation fails, `cxBufferInit()` returns non-zero, or `cxBufferCreate()` returns `NULL`, respectively.
 
 | Flag                     | Description                                                                                                                                                                                                   |
 |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|