# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1633429426 -7200
# Node ID 7fafc95968fc4d7a2530cefce1c55c2cb349f6c7
# Parent  92721c8f9db306dc0928fa620a9dadb1c95d1c7e
add documentation for list.h

diff -r 92721c8f9db3 -r 7fafc95968fc src/cx/list.h
--- a/src/cx/list.h	Tue Oct 05 12:19:19 2021 +0200
+++ b/src/cx/list.h	Tue Oct 05 12:23:46 2021 +0200
@@ -44,45 +44,156 @@
 extern "C" {
 #endif
 
+/**
+ * A comparator function comparing two list elements.
+ */
 typedef int(*CxListComparator)(void const *left, void const *right);
 
+/**
+ * Internal type for the list structure - use CxList instead.
+ */
 typedef struct cx_list_s cx_list_s;
 
+/**
+ * The class definition for arbitrary lists.
+ */
 typedef struct {
+    /**
+     * Member function for adding an element.
+     */
     int (*add)(cx_list_s *list, void *elem);
 
+    /**
+     * Member function for inserting an element.
+     */
     int (*insert)(cx_list_s *list, size_t index, void *elem);
 
+    /**
+     * Member function for removing an element.
+     */
     int (*remove)(cx_list_s *list, size_t index);
 
+    /**
+     * Member function for element lookup.
+     */
     void *(*at)(cx_list_s *list, size_t index);
 
+    /**
+     * Member function for finding an element.
+     */
     size_t (*find)(cx_list_s *list, void *elem);
 
+    /**
+     * Member function for retrieving the last element.
+     */
     void *(*last)(cx_list_s *list);
 } cx_list_class;
 
+/**
+ * Structure for holding the base data of a list.
+ */
 struct cx_list_s {
+    /**
+     * The list class definition.
+     */
     cx_list_class *cl;
+    /**
+     * The allocator to use.
+     */
     CxAllocator allocator;
+    /**
+     * The comparator function for the elements.
+     */
     CxListComparator cmpfunc;
+    /**
+     * The size of each element (payload only).
+     */
     size_t itemsize;
+    /**
+     * The size of the list (number of currently stored elements).
+     */
     size_t size;
+    /**
+     * The capacity of the list (maximum number of elements).
+     */
     size_t capacity;
 };
 
+/**
+ * Common type for all list implementations.
+ */
 typedef cx_list_s *CxList;
 
+/**
+ * Adds an item to the end of the list.
+ *
+ * \remark It is implementation defined whether
+ * the contents of the element are copied or the
+ * pointer is added to the list. In the latter case
+ * the \c itemsize of the list SHALL be \c sizeof(void*).
+ *
+ * @param list the list
+ * @param elem a pointer to the element to add
+ * @return zero on success, non-zero on memory allocation failure
+ */
 int cxListAdd(CxList list, void *elem);
 
+/**
+ * Inserts an item at the specified index.
+ *
+ * If \p index equals the list \c size, this is effectively cxListAdd().
+ *
+ * \remark It is implementation defined whether
+ * the contents of the element are copied or the
+ * pointer is added to the list. In the latter case
+ * the \c itemsize of the list SHALL be \c sizeof(void*).
+ *
+ * @param list the list
+ * @param index the index the element shall have
+ * @param elem a pointer to the element to add
+ * @return zero on success, non-zero on memory allocation failure
+ * or when the index is out of bounds
+ */
 int cxListInsert(CxList list, size_t index, void *elem);
 
+/**
+ * Removes the element at the specified index.
+ * @param list the list
+ * @param index the index of the element
+ * @return zero on success, non-zero if the index is out of bounds
+ */
 int cxListRemove(CxList list, size_t index);
 
+/**
+ * Returns a pointer to the element at the specified index.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @return a pointer to the element or \c NULL if the index is out of bounds
+ */
 void *cxListAt(CxList list, size_t index);
 
+/**
+ * Returns the index of the first element that equals \p elem.
+ *
+ * Determining equality is performed by the list's comparator function.
+ *
+ * @param list the list
+ * @param elem the element to find
+ * @return the index of the element or \c (size+1) if the element is not found
+ */
 size_t cxListFind(CxList list, void *elem);
 
+/**
+ * Returns a pointer to the last element of the list.
+ *
+ * This is effectively the same as cxListAt() with \c index=size-1, but
+ * this implementation may be more efficient depending on the list structure
+ * and the conrecte implementation of cxListAt().
+ *
+ * @param list the list
+ * @return a pointer to the last element or \c NULL if the list is empty
+ */
 void *cxListLast(CxList list);
 
 #ifdef __cplusplus