Clean up and inline comments

src/util/list.c

@@ -24,7 +24,7 @@
 #include "list.h"
 
 
-list_t *create_list(int elementSize, freeFunction freeFn)
+list_t *create_list(size_t elementSize, freeFunction freeFn)
 {
 	list_t *list;
 	list = (list_t *)calloc(1, sizeof(list_t));
@@ -103,20 +103,27 @@ void for_each_list(list_t *list, listIterator iterator)
 }
 
 void *head_list(list_t *list, bool removeFromList)
+// 
+// Warning: Caller is responsible for freeing the node->data returned. 
+//
 {
     assert(list->head != NULL);
 
     listNode *node = list->head;
     void *element = (void *)malloc(list->elementSize);
+	// Copying pointer to node->data
     memcpy(element, node->data, list->elementSize);
 
     if(removeFromList) {
+		// Disconnecting head node
         list->head = node->next;
         list->logicalLength--;
 
+		// Freeing pointer to node->data and node
         free(node->data);
         free(node);
     }
+	// Now element points to data formerly pointed to by node
 	return element;
 }
 

src/util/list.h

@@ -33,7 +33,7 @@ typedef struct _listNode {
 
 typedef struct {
   int logicalLength;
-  int elementSize;
+  size_t elementSize;
   listNode *head;
   listNode *tail;
   freeFunction freeFn;
@@ -44,7 +44,7 @@ typedef struct {
 @brief Initializes a linked list to store elements of elementSize and to call
 freeFunction for each element when destroying a list.
 */
-list_t *create_list(int elementSize, freeFunction freeFn);
+list_t *create_list(size_t elementSize, freeFunction freeFn);
 
 /**
 @brief Frees dynamically allocated nodes and optionally calls freeFunction

tests/util/test_list.cpp

@@ -111,6 +111,7 @@ BOOST_FIXTURE_TEST_CASE(test_head_list, FixtureStrings) {
     BOOST_CHECK(check_string(*(char **)temp, "David"));
     BOOST_CHECK(size_list(list) == 4);
 
+	// To free a node, free both the data and reference to data 
 	free_string(temp);
     free(temp);
 }