diff options
| author | David Robillard <d@drobilla.net> | 2022-11-17 12:07:21 -0500 |
|---|---|---|
| committer | David Robillard <d@drobilla.net> | 2022-11-17 12:09:45 -0500 |
| commit | 68d02a48ea89d45f16f7901bf46849ea923841c0 (patch) | |
| tree | dcab96020bd40c7e4d663d96701bba470abb08ce /doc | |
| parent | e0cb455ac899829cf9fe41bbd6015f5567a9bbcb (diff) | |
| download | zix-68d02a48ea89d45f16f7901bf46849ea923841c0.tar.gz zix-68d02a48ea89d45f16f7901bf46849ea923841c0.tar.bz2 zix-68d02a48ea89d45f16f7901bf46849ea923841c0.zip | |
Improve documentation
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/allocation.rst | 24 | ||||
| -rw-r--r-- | doc/error_handling.rst | 13 | ||||
| -rw-r--r-- | doc/meson.build | 2 | ||||
| -rw-r--r-- | doc/using_zix.rst | 2 |
4 files changed, 41 insertions, 0 deletions
diff --git a/doc/allocation.rst b/doc/allocation.rst new file mode 100644 index 0000000..5b9d507 --- /dev/null +++ b/doc/allocation.rst @@ -0,0 +1,24 @@ +.. + Copyright 2022 David Robillard <d@drobilla.net> + SPDX-License-Identifier: ISC + +Allocation +========== + +.. default-domain:: c +.. highlight:: c + +Functions or objects that allocate memory take a pointer to a :struct:`ZixAllocator`, +which can be used to customize the allocation scheme. +To simply use the system allocator, +callers can pass ``NULL``, +which is equivalent to :func:`zix_default_allocator()`. + +Zix includes one implementation of a custom allocator, +a very simple bump-pointer allocator which can be created with :func:`zix_bump_allocator`. + +A convenience API for using a custom allocator if provided +(and the system allocator otherwise) +is provided with functions like :func:`zix_malloc` that correspond to those in the standard C API. + +Memory allocated with an allocator must be freed by calling :func:`zix_free` with the same allocator. diff --git a/doc/error_handling.rst b/doc/error_handling.rst new file mode 100644 index 0000000..331aa33 --- /dev/null +++ b/doc/error_handling.rst @@ -0,0 +1,13 @@ +.. + Copyright 2022 David Robillard <d@drobilla.net> + SPDX-License-Identifier: ISC + +Error Handling +============== + +.. default-domain:: c +.. highlight:: c + +Most functions return a :enum:`ZixStatus` which describes whether they succeeded (with zero, or :enumerator:`ZIX_STATUS_SUCCESS`) +or why they failed. +The human-readable message for a status can be retrieved with :func:`zix_strerror`. diff --git a/doc/meson.build b/doc/meson.build index e9d3b52..d0f1952 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -28,6 +28,8 @@ if build_docs # Generated API Reference c_rst_files = files( + 'allocation.rst', + 'error_handling.rst', 'index.rst', 'string_views.rst', 'summary.rst', diff --git a/doc/using_zix.rst b/doc/using_zix.rst index f97ecf0..018140b 100644 --- a/doc/using_zix.rst +++ b/doc/using_zix.rst @@ -8,5 +8,7 @@ Using Zix .. toctree:: + error_handling string_views + allocation |