# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1650292154 -7200
# Node ID b070ef465313a7bfc188b1a9c30deac409070630
# Parent  536646d1575b8004bffdd7adbc4d96b199935867
simplify destructor signature (but loads more responsibility onto the user)

diff -r 536646d1575b -r b070ef465313 src/cx/allocator.h
--- a/src/cx/allocator.h	Mon Apr 18 15:59:09 2022 +0200
+++ b/src/cx/allocator.h	Mon Apr 18 16:29:14 2022 +0200
@@ -108,13 +108,13 @@
  * Function pointer type for destructor functions.
  *
  * A destructor function deallocates possible contents and MAY free the memory
- * pointed to by \p memory.
+ * pointed to by \p memory. Read the documentation of the respective function
+ * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
+ * particular implementation.
  *
  * @param memory a pointer to the object to destruct
- * @return \p memory if it has NOT been free'd by this destructor, otherwise \c NULL
   */
-typedef void *(*cx_destructor_func)(void *memory)
-        __attribute__((__nonnull__, __warn_unused_result__));
+typedef void (*cx_destructor_func)(void *memory) __attribute__((__nonnull__));
 
 /**
  * Allocate \p n bytes of memory.
diff -r 536646d1575b -r b070ef465313 src/cx/linked_list.h
--- a/src/cx/linked_list.h	Mon Apr 18 15:59:09 2022 +0200
+++ b/src/cx/linked_list.h	Mon Apr 18 16:29:14 2022 +0200
@@ -48,7 +48,8 @@
 /**
  * Allocates a linked list for storing elements with \p item_size bytes each.
  *
- * Elements added to the list are copied.
+ * @remark Elements added to the list are copied, therefore a possible cx_list_s.content_destructor
+ * MUST NOT free the memory pointed to by its argument.
  *
  * @param allocator the allocator for allocating the list nodes
  * @param comparator the comparator for the elements
@@ -66,6 +67,9 @@
  *
  * If you want to store the elements directly in this list, use cxLinkedListCreate().
  *
+ * @remark Since only pointers are stored in this list, a possible cx_list_s.content_destructor
+ * MAY free the memory pointed to by its argument in order to prevent memory leaks.
+ *
  * @param allocator the allocator for allocating the list nodes
  * @param comparator the comparator for the elements
  * @return the created list
@@ -78,6 +82,9 @@
 /**
  * Creates a linked list using the data from an array.
  *
+ * @remark Elements added to the list are copied, therefore a possible cx_list_s.content_destructor
+ * MUST NOT free the memory pointed to by its argument.
+ *
  * @param allocator the allocator for allocating the list nodes
  * @param comparator the comparator for the elements
  * @param item_size the size of one item in the array
diff -r 536646d1575b -r b070ef465313 src/cx/list.h
--- a/src/cx/list.h	Mon Apr 18 15:59:09 2022 +0200
+++ b/src/cx/list.h	Mon Apr 18 16:29:14 2022 +0200
@@ -72,6 +72,9 @@
     CxAllocator const *allocator;
     /**
      * An optional destructor for the list contents.
+     *
+     * @attention Read the documentation of the particular list implementation
+     * whether this destructor shall only destroy the contents or also free the memory.
      */
     cx_destructor_func content_destructor;
     /**
diff -r 536646d1575b -r b070ef465313 src/list.c
--- a/src/list.c	Mon Apr 18 15:59:09 2022 +0200
+++ b/src/list.c	Mon Apr 18 16:29:14 2022 +0200
@@ -32,7 +32,7 @@
     if (list->content_destructor != NULL) {
         CxIterator iter = cxListBegin(list);
         cx_foreach(void*, elem, iter) {
-            cxFree(list->allocator, list->content_destructor(elem));
+            list->content_destructor(elem);
         }
     }
     list->cl->destructor(list);