diff -r 3ec9cce0de01 -r a9f9c59e0b63 docs/Writerside/topics/properties.h.md
--- a/docs/Writerside/topics/properties.h.md Thu Feb 27 14:07:59 2025 +0100
+++ b/docs/Writerside/topics/properties.h.md Fri Feb 28 19:07:47 2025 +0100
@@ -64,8 +64,58 @@
char *buf, size_t capacity);
```
+The first step is to initialize a `CxProperties` structure with a call to `cxPropertiesInit()` using the desired config.
+The shorthand `cxPropertiesInitDefault()` creates a default configuration with the equals sign `'='` as delimiter
+and the hash-symbol `'#'` as comment symbol (the other two comment symbols remain unused in the default config).
+
+> In a future UCX version, the default `continuation` character will be a backslash `'\'`.
+> In UCX 3.1 this feature is not implemented, yet.
+
+The actual parsing is an interleaving invocation of the `cxPropertiesFill()` (or `cxPropertiesFilln()`) and `cxPropertiesNext()` functions.
+The `cxPropertiesFill()` function is a convenience function, that accepts UCX strings and normal zero-terminated C strings and behaves otherwise like `cxPropertiesFilln()`.
+
+Filling the input buffer is cost-free if there is no data already in the input buffer.
+In that case, the input buffer only stores the pointer to the original data without creating a copy.
+Calling `cxPropertiesNext()` will return with `CX_PROPERTIES_NO_ERROR` (= zero) for each key/value-pair that is successfully parsed,
+and stores the pointers and lengths for both the key and the value into the structures pointed to by the `key` and `value` arguments.
+
+> This is all still free of any copies and allocations.
+> That means, the pointers in `key` and `value` after `cxPropertiesNext()` returns will point into the input buffer.
+> If you intend to store the key and/or the value somewhere else, it is strongly recommended to create a copy with `cx_strdup()`,
+> because you will otherwise soon end up with a dangling pointer.
+> {style="note"}
+
+If `cxPropertiesNext()` returns `CX_PROPERTIES_INCOMPLETE_DATA` it means that the input buffer is exhausted,
+but the last line did not contain a full key/value pair.
+In that case, you can call `cxPropertiesFill()` again to add more data and continue with `cxPropertiesNext()`.
+
+Note, that adding more data to a non-empty input buffer will lead to an allocation,
+unless you specified some stack memory with `cxPropertiesUseStack()`.
+The stack capacity must be large enough to contain the longest line in your data.
+If the internal buffer is not large enough to contain a single line, it is extended.
+If that is not possible for some reason, `cxPropertiesNext()` fails and returns `CX_PROPERTIES_BUFFER_ALLOC_FAILED`.
+
+If you want to reuse a `CxProperties` structure with the same config, you can call `cxPropertiesReset()`, even if the last operation was a failure.
+Otherwise, you should always call `cxPropertiesDestroy()` when you are done with the parser.
+
+> It is strongly recommended to always call `cxPropertiesDestroy` when you are done with the parser,
+> even if you did not expect any allocations because you used `cxPropertiesUseStack()`.
+
### List of Status Codes
+Below is a full list of error codes for `cxPropertiesNext()`.
+
+| Status Code | Meaning |
+|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| CX_PROPERTIES_NO_ERROR | A key/value pair was found and returned. |
+| CX_PROPERTIES_NO_DATA | The input buffer does not contain more data. |
+| CX_PROPERTIES_INCOMPLETE_DATA | The input ends unexpectedly. This can happen when the last line does not terminate with a line break, or when the input ends with a parsed key but no value. Use `cxPropertiesFill()` to add more data before retrying. |
+| CX_PROPERTIES_NULL_INPUT | The input buffer was never initialized. Probably you forgot to call `cxPropertiesFill()` at least once. |
+| CX_PROPERTIES_INVALID_EMPTY_KEY | Only white-spaces were found on the left hand-side of the delimiter. Keys must not be empty. |
+| CX_PROPERTIES_INVALID_MISSING_DELIMITER | A line contains data, but no delimiter. |
+| CX_PROPERTIES_BUFFER_ALLOC_FAILED | More internal buffer was needed, but could not be allocated. |
+
+
## Sources and Sinks
```C
@@ -91,6 +141,22 @@
CxPropertiesSink sink, CxPropertiesSource source);
```
+
+TODO: write documentation
+
+
+### Additional Status Codes
+
+For sources and sinks there are three additional special status codes,
+which only appear as return values for `cxPropertiesLoad()`.
+
+| Status Code | Meaning |
+|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| CX_PROPERTIES_READ_INIT_FAILED | Initializing the properties source failed and the `cx_properties_read_init_func` returned non-zero. |
+| CX_PROPERTIES_READ_FAILED | Reading from a properties source failed and the `cx_properties_read_func` returned non-zero. |
+| CX_PROPERTIES_SINK_FAILED | Sinking a key/value-pair failed and the `cx_properties_sink_func` returned non-zero. |
+
+
### Creating own Sources and Sinks
```C
@@ -124,6 +190,10 @@
} CxPropertiesSink;
```
+
+TODO: write documentation
+
+
properties.h