From 68d02a48ea89d45f16f7901bf46849ea923841c0 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 17 Nov 2022 12:07:21 -0500 Subject: Improve documentation --- doc/allocation.rst | 24 ++++++++++++++++++++++++ doc/error_handling.rst | 13 +++++++++++++ doc/meson.build | 2 ++ doc/using_zix.rst | 2 ++ 4 files changed, 41 insertions(+) create mode 100644 doc/allocation.rst create mode 100644 doc/error_handling.rst (limited to 'doc') 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 + 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 + 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 -- cgit v1.2.1