add Doxygen documentation (partially)

2008-11-28 10:48:39 +00:00
parent 83337fea15
commit 925be143ac
1 changed files with 317 additions and 146 deletions
@@ -1,3 +1,19 @@
+/** \file LL.c
+ * Define routines to deal with doubly linked lists
+ */
+
+/* This file is part of LCDproc.
+ *
+ * This file is released under the GNU General Public License. Refer to the
+ * COPYING file distributed with this package.
+ *
+ * Copyright(c) 1999, William Ferrell
+ *          (c) 2000, Guillaume Filion
+ *          (c) 2001, Joris Robijn
+ *          (c) 2008, Peter Marschall
+ *
+ */
+
 #include <stdlib.h>
 #include <stdio.h>
 #include "LL.h"
@@ -9,8 +25,10 @@
 //TODO: Comment everything
 //TODO: Test everything?

-//////////////////////////////////////////////////////////////////////
-// Creates a new list...
+
+/** Create new linked list.
+ * \return Pointer to freshly created list object; \c NULL on error.
+ */
 LinkedList *
 LL_new()
 {
@@ -31,10 +49,15 @@ LL_new ()
 	return list;
 }

-//////////////////////////////////////////////////////////////////////
-// TODO: test this function
-// Destroys the entire list
-// Warning!  Does not free the list data! (only the list itself)
+
+/** Destroy the entire list.
+ *
+ * Note: this does not free the data, only the list itself
+ *
+ * \param list   List object to be destroyed.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
 LL_Destroy(LinkedList *list)
 {
@@ -57,9 +80,15 @@ LL_Destroy (LinkedList * list)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
-// TODO: test this function
-// Warning!  This does not assert that the node data is free!
+
+/** Destroy a node.
+ *
+ * Warning!  This does not assert that the node data is free!
+ *
+ * \param node   Node to be destroyed.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
 LL_node_Destroy(LL_node *node)
 {
@@ -74,7 +103,12 @@ LL_node_Destroy (LL_node * node)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Unlink a node from the list.
+ * \param node   Node to be unlinked.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
 LL_node_Unlink(LL_node *node)
 {
@@ -97,23 +131,35 @@ LL_node_Unlink (LL_node * node)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
-// Frees the data in a list node, if not NULL...
+
+/** Free the data in a list node.
+ * \param node   Node, whose data is to be destroyed.
+ * \retval <0    error: illegal node, or no node data to destroy.
+ * \retval  0	 success
+ */
 int
 LL_node_DestroyData(LL_node *node)
 {
 	if (!node)
 		return -1;

-	if (node->data)
+	if (node->data) {
 		free(node->data);
+		// prevent accidential double free()
+		node->data = NULL;
+	}
 	else
 		return -1;
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
-// Returns to the beginning of the list...
+
+/* Return to the beginning of the list.
+ * Set list's "current" pointer to the first node in the list.
+ * \param list   List object.
+ * \retval <0    error: no list given
+ * \retval  0	 success
+ */
 int
 LL_Rewind(LinkedList *list)
 {
@@ -133,8 +179,13 @@ LL_Rewind (LinkedList * list)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
-// Goes to the end of the list...
+
+/** Jump to the end of the list.
+ * Set list's "current" pointer to the last node in the list.
+ * \param list   List object.
+ * \retval <0    error: no list given
+ * \retval  0	 success
+ */
 int
 LL_End(LinkedList *list)
 {
@@ -149,8 +200,13 @@ LL_End (LinkedList * list)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
-// Go to the next node
+
+/** Go to the next node of the list.
+ * Advance list's "current" pointer to the next node in the list.
+ * \param list   List object.
+ * \retval <0    error: no list given or no next node
+ * \retval  0	 success
+ */
 int
 LL_Next(LinkedList *list)
 {
@@ -167,8 +223,13 @@ LL_Next (LinkedList * list)
 	}
 }

-//////////////////////////////////////////////////////////////////////
-// Go to the previous node
+
+/** Go to the previous node of the list.
+ * Set list's "current" pointer to the previous node in the list.
+ * \param list   List object.
+ * \retval <0    error: no list given or no previous node
+ * \retval  0	 success
+ */
 int
 LL_Prev(LinkedList *list)
 {
@@ -185,8 +246,12 @@ LL_Prev (LinkedList * list)
 	}
 }

-//////////////////////////////////////////////////////////////////////
-// Data manipulation
+
+/** Access current node's data.
+ * \param list   List object.
+ * \retval <0    error: no list given, or no data in current node
+ * \retval  0	 success
+ */
 void *
 LL_Get(LinkedList *list)
 {
@@ -198,7 +263,13 @@ LL_Get (LinkedList * list)
 	return list->current->data;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Set/change current node's data.
+ * \param list   List object.
+ * \param data   Pointer to data to be set.
+ * \retval <0    error: no list given, or no current node
+ * \retval  0	 success
+ */
 int
 LL_Put(LinkedList *list, void *data)
 {
@@ -212,7 +283,11 @@ LL_Put (LinkedList * list, void *data)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Get current node in list.
+ * \param list   List object.
+ * \return       Pointer to current node.
+ */
 LL_node *
 LL_GetNode(LinkedList *list)
 {
@@ -222,8 +297,16 @@ LL_GetNode (LinkedList * list)
 	return list->current;
 }

-//////////////////////////////////////////////////////////////////////
-// Don't use this unless you know what you're doing.
+
+/** Set list's current pointr to a specific node.
+ *
+ * Warning: Don't use this unless you know what you're doing.
+ *
+ * \param list   List object.
+ * \param list   List object.
+ * \retval <0    error
+ * \retval  0    success
+ */
 int
 LL_PutNode(LinkedList *list, LL_node *node)
 {
@@ -237,9 +320,14 @@ LL_PutNode (LinkedList * list, LL_node * node)
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Access list's first node's data.
+ * Set list's "current" pointer to the first node and return its data.
+ * \param list   List object.
+ * \return       Pointer to first node's data; \c NULL on error.
+ */
 void *
-LL_GetFirst (LinkedList * list)			  // gets data from first node
+LL_GetFirst(LinkedList *list)
 {
 	if (!list)
 		return NULL;
@@ -250,10 +338,14 @@ LL_GetFirst (LinkedList * list)			  // gets data from first node
 	return LL_Get(list);
 }

-//////////////////////////////////////////////////////////////////////
-//
+
+/** Access next node's data.
+ * Advance list's "current" pointer to the next node and return its data.
+ * \param list   List object.
+ * \return       Pointer to next node's data; \c NULL on error.
+ */
 void *
-LL_GetNext (LinkedList * list)			  //            ... next node
+LL_GetNext(LinkedList *list)
 {
 	if (!list)
 		return NULL;
@@ -264,9 +356,14 @@ LL_GetNext (LinkedList * list)			  //            ... next node
 	return LL_Get(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Access previous node's data.
+ * Set list's "current" pointer to the previous node, and return its data.
+ * \param list   List object.
+ * \return       Pointer to previous node's data; \c NULL on error.
+ */
 void *
-LL_GetPrev (LinkedList * list)			  //            ... prev node
+LL_GetPrev(LinkedList *list)
 {
 	if (!list)
 		return NULL;
@@ -277,9 +374,14 @@ LL_GetPrev (LinkedList * list)			  //            ... prev node
 	return LL_Get(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Access list's last node's data.
+ * Set list's "current" pointer to the last node and return its data.
+ * \param list   List object.
+ * \return       Pointer to last node's data; \c NULL on error.
+ */
 void *
-LL_GetLast (LinkedList * list)			  //            ... last node
+LL_GetLast(LinkedList *list)
 {
 	if (!list)
 		return NULL;
@@ -290,9 +392,15 @@ LL_GetLast (LinkedList * list)			  //            ... last node
 	return LL_Get(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Add/append a new node after current one in the list.
+ * \param list   List object.
+ * \param add    Pointer to new node's data.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
-LL_AddNode (LinkedList * list, void *add)	// Adds node AFTER current one
+LL_AddNode(LinkedList *list, void *add)
 {
 	LL_node *node;

@@ -346,9 +454,15 @@ LL_AddNode (LinkedList * list, void *add)	// Adds node AFTER current one
 	return 0;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Add/insert a new node before current one in the list.
+ * \param list   List object.
+ * \param add    Pointer to new node's data.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
-LL_InsertNode (LinkedList * list, void *add)	// Adds node BEFORE current one
+LL_InsertNode(LinkedList *list, void *add)
 {
 	LL_node *node;

@@ -431,8 +545,13 @@ LL_DeleteNode (LinkedList * list)
 	return data;
 }

-//////////////////////////////////////////////////////////////////////
-// Removes a specific node...
+
+/** Remove a specific node from the list.
+ * find a node by a pointer to it's data and remove it.
+ * \param list   List object.
+ * \param data   Pointer to data of not to delete.
+ * \return       Pointer to data of deleted node; \c NULL on error.
+ */ 
 void *
 LL_Remove(LinkedList *list, void *data)
 {
@@ -451,8 +570,14 @@ LL_Remove (LinkedList * list, void *data)
 	return NULL;
 }

-//////////////////////////////////////////////////////////////////////
-// Stack operations
+
+/** Add/append a new node after the last one in the list.
+ * Jump to the last node in the list and append a new node.
+ * \param list   List object.
+ * \param add    Pointer to new node's data.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
 LL_Push(LinkedList *list, void *add)  // Add node to end of list
 {
@@ -468,7 +593,12 @@ LL_Push (LinkedList * list, void *add)  // Add node to end of list
 	return LL_AddNode(list, add);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Remove the last node from the list, and return its data.
+ * Jump to the last node in the list, remove it from the list and return its data.
+ * \param list   List object.
+ * \return       Pointer to data of deleted node; \c NULL on error.
+ */
 void *
 LL_Pop(LinkedList *list)				  // Remove node from end of list
 {
@@ -481,14 +611,24 @@ LL_Pop (LinkedList * list)				  // Remove node from end of list
 	return LL_DeleteNode(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Access list's last node's data.
+ * Set list's "current" pointer to the last node and return its data.
+ * \param list   List object.
+ * \return       Pointer to last node's data; \c NULL on error.
+ */
 void *
 LL_Top(LinkedList *list)				  // Peek at end node
 {
 	return LL_GetLast(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Remove the first node from the list, and return its data.
+ * Jump to the first node in the list, remove it from the list and return its data.
+ * \param list   List object.
+ * \return       Pointer to data of deleted node; \c NULL on error.
+ */
 void *
 LL_Shift(LinkedList *list)				  // Remove node from start of list
 {
@@ -501,14 +641,26 @@ LL_Shift (LinkedList * list)				  // Remove node from start of list
 	return LL_DeleteNode(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Access list's first node's data.
+ * Set list's "current" pointer to the first node and return its data.
+ * \param list   List object.
+ * \return       Pointer to first node's data; \c NULL on error.
+ */
 void *
 LL_Look(LinkedList *list)				  // Peek at first node
 {
 	return LL_GetFirst(list);
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Add/insert a new node before the first one in the list.
+ * Jump to the first node in the list and insert a new node before that one.
+ * \param list   List object.
+ * \param add    Pointer to new node's data.
+ * \retval <0    error
+ * \retval  0	 success
+ */
 int
 LL_Unshift(LinkedList *list, void *add)	// Add node to beginning of list
 {
@@ -522,6 +674,7 @@ LL_Unshift (LinkedList * list, void *add)	// Add node to beginning of list
 	return LL_InsertNode(list, add);
 }

+
 //////////////////////////////////////////////////////////////////////
 int
 LL_Roll(LinkedList *list)				  // Make last node first
@@ -564,6 +717,7 @@ LL_Roll (LinkedList * list)				  // Make last node first
 	return 0;
 }

+
 //////////////////////////////////////////////////////////////////////
 int
 LL_UnRoll(LinkedList *list)			  // Roll the other way...
@@ -606,6 +760,7 @@ LL_UnRoll (LinkedList * list)			  // Roll the other way...
 	return 0;
 }

+
 //////////////////////////////////////////////////////////////////////
 // Add an item to the end of its "priority group"
 // The list is assumed to be sorted already...
@@ -643,6 +798,7 @@ LL_PriorityEnqueue (LinkedList * list, void *add, int compare (void *, void *))
 	return 0;
 }

+
 //////////////////////////////////////////////////////////////////////
 int
 LL_SwapNodes(LL_node *one, LL_node *two)	// Switch two nodes positions...
@@ -687,6 +843,7 @@ LL_SwapNodes (LL_node * one, LL_node * two)	// Switch two nodes positions...

 }

+
 //////////////////////////////////////////////////////////////////////
 int
 LL_nSwapNodes(int one, int two)	// Switch two nodes positions...
@@ -694,7 +851,11 @@ LL_nSwapNodes (int one, int two)	// Switch two nodes positions...
 	return -1;
 }

-//////////////////////////////////////////////////////////////////////
+
+/** Calculate the length of a list.
+ * \param list   List object.
+ * \return       Number of nodes in the list; \c -1 on error.
+ */
 int
 LL_Length(LinkedList *list)			  // Returns # of nodes in entire list
 {
@@ -712,6 +873,7 @@ LL_Length (LinkedList * list)			  // Returns # of nodes in entire list
 	return num;
 }

+
 //////////////////////////////////////////////////////////////////////
 // Searching...
 // Goes to the list item which matches "value", and returns the
@@ -743,6 +905,7 @@ LL_Find (LinkedList * list, int compare (void *, void *), void *value)
 	return NULL;
 }

+
 //////////////////////////////////////////////////////////////////////
 // Array like...
 // Goes to the nth list item, and returns the
@@ -767,9 +930,17 @@ LL_GetByIndex (LinkedList * list, int index)
 	return NULL; // got past the end
 }

-//////////////////////////////////////////////////////////////////////
-// Sorts the list, then rewinds it...
-//
+
+/** Sort list by its contents.
+ * The list gets sorted using a comparison function for the data of its nodes.
+ * After the sorting, the list's current pointer is set to the first node.
+ * \param list     List object.
+ * \param compare  Pointer to a comparison function, that takes to void pointers
+                   is arguments and returns an int > 0 when the first argument
+                   is considered greater then the second.
+ * \retval <0      error
+ * \retval  0      success.
+ */
 int
 LL_Sort(LinkedList *list, int compare(void *, void *))
 {