# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1632665541 -7200
# Node ID 3d8235c96a2724612d6bb59566478c95cbc8c5f2
# Parent  da66264af8ad6457fa409a8573a54de69a0daef3
add documentation to allocator.h

diff -r da66264af8ad -r 3d8235c96a27 src/cx/allocator.h
--- a/src/cx/allocator.h	Sun Sep 26 15:26:43 2021 +0200
+++ b/src/cx/allocator.h	Sun Sep 26 16:12:21 2021 +0200
@@ -25,6 +25,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \file allocator.h
+ * Interface for custom allocators.
+ */
 
 #ifndef UCX_ALLOCATOR_H
 #define UCX_ALLOCATOR_H
@@ -35,29 +39,136 @@
 extern "C" {
 #endif
 
+/**
+ * The class definition for an allocator.
+ */
 typedef struct {
+    /**
+     * Allocate \p n bytes of memory.
+     *
+     * @param data the allocator's data
+     * @param n the number of bytes
+     * @return a pointer to the allocated memory
+     */
     void *(*malloc)(void *data, size_t n);
+
+    /**
+     * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
+     * This function may return the same pointer that was passed to it, if moving the memory
+     * was not necessary.
+     *
+     * \note Re-allocating a block allocated by a different allocator is undefined.
+     *
+     * @param data the allocator's data
+     * @param mem pointer to the previously allocated block
+     * @param n the new size in bytes
+     * @return a pointer to the re-allocated memory
+     */
     void *(*realloc)(void *data, void *mem, size_t n);
+
+    /**
+     * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
+     *
+     * @param data the allocator's data
+     * @param nelem the number of elements
+     * @param n the size of each element in bytes
+     * @return a pointer to the allocated memory
+     */
     void *(*calloc)(void *data, size_t nelem, size_t n);
-    void(*free)(void *data, void *mem);
+
+    /**
+     * Free a block allocated by this allocator.
+     *
+     * \note Freeing a block of a different allocator is undefined.
+     *
+     * @param data the allocator's data
+     * @param mem a pointer to the block to free
+     */
+    void (*free)(void *data, void *mem);
 } cx_allocator_class;
 
+/**
+ * Structure holding the data for an allocator.
+ */
 struct cx_allocator_s {
+    /**
+     * A pointer to the instance of the allocator class.
+     */
     cx_allocator_class *cl;
+    /**
+     * A pointer to the data this allocator uses.
+     */
     void *data;
 };
+
+/**
+ * High-Level type alias for the allocator type.
+ */
 typedef struct cx_allocator_s *CxAllocator;
 
+/**
+ * A default allocator using standard library malloc() etc.
+ */
 extern CxAllocator cxDefaultAllocator;
 
+/**
+ * Allocate \p n bytes of memory.
+ *
+ * @param allocator the allocator
+ * @param n the number of bytes
+ * @return a pointer to the allocated memory
+ */
 void *cxMalloc(CxAllocator allocator, size_t n);
 
+/**
+ * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
+ * This function may return the same pointer that was passed to it, if moving the memory
+ * was not necessary.
+ *
+ * \note Re-allocating a block allocated by a different allocator is undefined.
+ *
+ * @param allocator the allocator
+ * @param mem pointer to the previously allocated block
+ * @param n the new size in bytes
+ * @return a pointer to the re-allocated memory
+ */
 void *cxRealloc(CxAllocator allocator, void *mem, size_t n);
 
+/**
+ * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
+ * This function acts like cxRealloc() using the pointer pointed to by \p mem.
+ * On success, the pointer is changed to the new location (in case the
+ *
+ * \note Re-allocating a block allocated by a different allocator is undefined.
+ *
+ * \par Error handling
+ * \c errno will be set, if the underlying realloc function does so.
+ *
+ * @param allocator the allocator
+ * @param mem pointer to the pointer to allocated block
+ * @param n the new size in bytes
+ * @return zero on success, non-zero on failure
+ */
 int cxReallocate(CxAllocator allocator, void **mem, size_t n);
 
+/**
+ * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
+ *
+ * @param allocator the allocator
+ * @param nelem the number of elements
+ * @param n the size of each element in bytes
+ * @return a pointer to the allocated memory
+ */
 void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n);
 
+/**
+ * Free a block allocated by this allocator.
+ *
+ * \note Freeing a block of a different allocator is undefined.
+ *
+ * @param allocator the allocator
+ * @param mem a pointer to the block to free
+ */
 void cxFree(CxAllocator allocator, void *mem);
 
 #ifdef __cplusplus