[hipl-commit] [trunk] Rev 3567: Doxygen for dlist.c
- From: Miika Komu <miika@xxxxxx>
- To: hipl-commit@xxxxxxxxxxxxx
- Date: Tue, 9 Feb 2010 16:10:37 +0200
Committer: Miika Komu <miika@xxxxxx>
Date: Tue Feb 09 16:10:47 2010 +0200
Revision: 3567
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk
Log:
Doxygen for dlist.c
Modified:
D firewall/dlist.c.doxyme
M firewall/dlist.c
=== modified file 'firewall/dlist.c'
--- firewall/dlist.c 2009-12-29 14:57:20 +0000
+++ firewall/dlist.c 2010-02-09 14:10:47 +0000
@@ -1,5 +1,24 @@
+/**
+ * @file firewall/dlist.c
+ *
+ * Distributed under <a
href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>.
+ *
+ * Linked list implementation operating based on pointers. It is
+ * recommended to use lib/core/list.h implementation which supports
+ * searching based on indexes (rather than pointers) can later also be
+ * easily changed into a hashtable if needed.
+ *
+ * @brief Simple linked list implementation
+ *
+ **/
+
#include "dlist.h"
+/**
+ * Initialize and allocate memory for a new linked list.
+ *
+ * @return the linked list (caller frees)
+ */
DList * alloc_list (void) {
DList * list = (DList *) malloc (sizeof(DList));
list->data = NULL;
@@ -9,13 +28,19 @@
return list;
}
+/**
+ * Remove a link from the list
+ *
+ * @param the link to be removed
+ * @return a pointer to the original list
+ **/
DList * free_list_chain (DList * list) {
+ DList * tmp = NULL;
+
if (!list) {
return NULL;
}
- DList * tmp = NULL;
-
if (list->prev) {
tmp = list->prev;
tmp->next = list->next;
@@ -29,6 +54,16 @@
return tmp;
}
+/**
+ * Deallocate the memory allocated for the entire linked list.
+ * If the linked list items contain pointer to other allocated
+ * items, the caller must free them beforehand!
+ *
+ * @todo (what's the difference to the previous function?)
+ *
+ * @param list the list to be deallocated
+ * @return a pointer to the original list
+ **/
void free_list (DList * list) {
DList * head = list_first (list);
@@ -46,6 +81,12 @@
}
}
+/**
+ * get a pointer to the previous list item
+ *
+ * @param list a pointer to the list
+ * @return a pointer to the previous list item
+ **/
DList * list_first (DList * list) {
if (list) {
while (list->prev) {
@@ -56,6 +97,12 @@
return list;
}
+/**
+ * get a pointer to the next list item
+ *
+ * @param list a pointer to the list
+ * @return a pointer to the next list item
+ **/
DList * list_last (DList * list) {
if (list) {
while (list->next) {
@@ -66,6 +113,12 @@
return list;
}
+/**
+ * calculate the number of list items
+ *
+ * @param list the linked list
+ * @return the number of items on the linked list
+ **/
unsigned int list_length (DList * list) {
unsigned int length = 0;
list = list_first (list);
@@ -78,8 +131,15 @@
return length;
}
+/**
+ * append a new element to the linked list
+ *
+ * @param list the linked list
+ * @param data the new item to be appended
+ * @return a pointer to the new item in the linked list
+ **/
DList * append_to_list (DList * list,
- void * data) {
+ void * data) {
DList *new_list;
DList *last;
@@ -104,8 +164,15 @@
}
}
+/**
+ * remove an element from the linked list by searching
+ *
+ * @param list the linked list
+ * @param data the element to be removed
+ * @return a pointer to the linked list
+ **/
DList * remove_from_list (DList * list,
- const void * data) {
+ const void * data) {
DList * tmp;
tmp = list;
@@ -132,9 +199,14 @@
return list;
}
-DList *
-remove_link_dlist (DList * list,
- DList * link) {
+/**
+ * remove a given link from the linked list
+ *
+ * @param the linked list
+ * @return link the link to be removed
+ **/
+DList * remove_link_dlist (DList * list,
+ DList * link) {
if (link) {
if ( link->prev) {
link->prev->next = link->next;
@@ -152,8 +224,15 @@
return list;
}
-DList* find_in_dlist (DList * list,
- void * data) {
+/**
+ * find an element in the linked list
+ *
+ * @param list the linked list
+ * @param data the element to find
+ * @return the element in the linked list
+ **/
+DList *find_in_dlist (DList * list,
+ void * data) {
while (list) {
if (list->data == data) {
break;
=== removed file 'firewall/dlist.c.doxyme'
--- firewall/dlist.c.doxyme 2009-12-12 10:44:54 +0000
+++ firewall/dlist.c.doxyme 1970-01-01 00:00:00 +0000
@@ -1,125 +0,0 @@
-/**
- * @file firewall/dlist.c
- *
- * <LICENSE TEMLPATE LINE - LEAVE THIS LINE INTACT>
- *
- * Write description of source file here for dOxygen. Be as precise as
possible.
- * Please also note how and by which parts of the code this file should be
used.
- *
- * @brief Write a short summary
- *
- * @author <Put all existing author information here>
- * @author another Author another@xxxxxxxxxx
- **/
-
-
-
- /// Single line comment for dOxygen.
-
-/**
- * my_great_function
- *
- * Write description of function here.
- * The function should follow these comments.
- *
- * Document the use of each function variable and indicate if this
- * argument is used to return information to the calling context. Use
- * [out] for outut parameters (This is very important). Align the
- * descriptions to improve readability.
- *
- * @note: put important usage informations to notes.
- *
- * @param firstArg Description of first function argument.
- * @param[out] secondArg Description of second function argument.
- * @param thirdArg Description of third function argument.
- * @return Description of returned value.
- **/
-
-int my_great_function(int firstArg, char** secondArg, int thirdArg){
- .....
-
-/// Now it's your turn.
-
-
-
-
-/**
- * append_to_list
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * find_in_dlist
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * free_list
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * free_list_chain
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * list_first
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * list_last
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * list_length
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * remove_from_list
- *
- *
- * @param autogen.sh
- * @return
- **/
-
-
-/**
- * remove_link_dlist
- *
- *
- * @param autogen.sh
- * @return
- **/
-
Other related posts:
- » [hipl-commit] [trunk] Rev 3567: Doxygen for dlist.c - Miika Komu
