1 files changed, 160 insertions, 337 deletions

diff --git a/libical/src/libical/pvl.c b/libical/src/libical/pvl.c
index 2a733e8..9c271ce 100644
--- a/libical/src/libical/pvl.c
+++ b/libical/src/libical/pvl.c
@@ -17,5 +17,3 @@
 
-
-
-/*
+/**
   struct pvl_list_t
@@ -30,7 +28,7 @@ typedef struct pvl_list_t
 {
-                int MAGIC;              /* Magic Identifier */
-                struct pvl_elem_t *head;/* Head of list */
-                struct pvl_elem_t *tail;/* Tail of list */
-                int count;              /* Number of items in the list */
-                struct pvl_elem_t *p;   /* Pointer used for iterators */
+                int MAGIC;              /**< Magic Identifier */
+                struct pvl_elem_t *head;/**< Head of list */
+                struct pvl_elem_t *tail;/**< Tail of list */
+                int count;              /**< Number of items in the list */
+                struct pvl_elem_t *p;   /**< Pointer used for iterators */
 } pvl_list_t;
@@ -40,4 +38,6 @@ typedef struct pvl_list_t
 
-/* This global is incremented for each call to pvl_new_element(); it gives each
- * list a unique identifer */
+/**
+ * This global is incremented for each call to pvl_new_element(); it gives each
+ * list a unique identifer 
+ */
 
@@ -47,14 +47,7 @@ int pvl_list_count = 0;
 
-/*----------------------------------------------------------------------
-  Function: pvl_list pvl_newlist()
- 
-  Purpose:
-
-  Creates a new list, clears the pointers and assigns a magic number
-
-  Returns:
-
-  Pointer to the new list
-  0 if there is no available memory. 
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Creates a new list, clears the pointers and assigns a magic number
+ * 
+ * @return  Pointer to the new list, 0 if there is no available memory. 
+ */
 
@@ -91,28 +84,19 @@ pvl_free(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function: pvl_new_element(void *d, struct pvl_elem_t *next,struct pvl_elem_t *prior)
- 
-  Purpose:
-  Creates a new list element, assigns a magic number, and assigns 
-  the next and previous pointers. 
-
-  Passing in the next and previous points may seem odd, but it allos the user
-  to set them while keeping the internal data hidden. In nearly all cases, 
-  the user is the pvl library itself. 
-
-  Parameters:
-
-          dThe data item to be stored in the list
-  next  Pointer value to assign to the member "next"
-  prior Pointer value to assign to the member "prior"
-
-  Returns:
-  
-  A pointer to the new element.
-  0 if there is no memory available. 
-
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Creates a new list element, assigns a magic number, and assigns 
+ * the next and previous pointers. 
+ * 
+ * Passing in the next and previous points may seem odd, but it allos the user
+ * to set them while keeping the internal data hidden. In nearly all cases, 
+ * the user is the pvl library itself. 
+ *
+         * @param dThe data item to be stored in the list
+ * @param next  Pointer value to assign to the member "next"
+ * @param prior Pointer value to assign to the member "prior"
+ *
+ * @return A pointer to the new element, 0 if there is no memory available. 
+ */
 
 pvl_elem 
-pvl_new_element(void *d, pvl_elem next,pvl_elem prior)
+pvl_new_element(void *d, pvl_elem next, pvl_elem prior)
 {
@@ -134,21 +118,12 @@ pvl_new_element(void *d, pvl_elem next,pvl_elem prior)
 
-/*----------------------------------------------------------------------
-  Function: pvl_unshift(pvl_list l,void *d)
- 
-  Purpose:
-
-  Add a new element to the from of the list
-
-  Parameters:
-
-          lThe list to add the item to 
-          dPointer to the item to add
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Add a new element to the from of the list
+ *
+         * @param LThe list to add the item to 
+         * @param dPointer to the item to add
+ */
 
 void 
-pvl_unshift(pvl_list l,void *d)
+pvl_unshift(pvl_list L,void *d)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
     struct pvl_elem_t *E = pvl_new_element(d,L->head,0);
@@ -174,21 +149,13 @@ pvl_unshift(pvl_list l,void *d)
 
-/*----------------------------------------------------------------------
-  Function: pvl_shift(pvl_list l)
- 
-  Purpose:
-
-  Remove an element from the front of the list 
-
-  Parameters:
-
-          lThe list to operate on
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Remove an element from the front of the list 
+ *
+         * @param LThe list to operate on
+ *
+ * @return the entry on the front of the list 
+ */
 
 void* 
-pvl_shift(pvl_list l)
+pvl_shift(pvl_list L)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-
     if (L->head == 0)
@@ -198,3 +165,3 @@ pvl_shift(pvl_list l)
 
-    return pvl_remove(l,(void*)L->head);
+    return pvl_remove(L,(void*)L->head);
 
@@ -202,21 +169,13 @@ pvl_shift(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function: void  pvl_push(pvl_list l,void *d)
-
-  Purpose:
-
-  Add a new item to the tail of the list
-
-  Paramters:
-
-          lThe list to operate on
-          dPointer to the item to add
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Add a new item to the tail of the list
+ *
+         * @param LThe list to operate on
+         * @param dPointer to the item to add
+ *
+ */
 
 void 
-pvl_push(pvl_list l,void *d)
+pvl_push(pvl_list L,void *d)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
     struct pvl_elem_t *E = pvl_new_element(d,0,L->tail);
@@ -244,22 +203,11 @@ pvl_push(pvl_list l,void *d)
 
-/*----------------------------------------------------------------------
-  Function: void*  pvl_pop(pvl_list l)
-
-  Purpose:
-
-  Remove an element from the tail of the list 
-
-  Paramters:
-
-          lThe list to operate on
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Remove an element from the tail of the list 
+ *
+         * @param LThe list to operate on
+ */
 
 void* 
-pvl_pop(pvl_list l)
+pvl_pop(pvl_list L)
 {
-
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-
     if ( L->tail == 0)
@@ -269,3 +217,3 @@ pvl_pop(pvl_list l)
 
-    return pvl_remove(l,(void*) L->tail);;
+    return pvl_remove(L,(void*) L->tail);;
 
@@ -274,25 +222,14 @@ pvl_pop(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function: void pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
-
-  Purpose:
-  
-  Add a new item to a list that is ordered by a comparison function. 
-  This routine assumes that the list is properly ordered. 
-
-          lThe list to operate on
-          fPointer to a comparison function
-  d     Pointer to data to pass to the comparison function
-
-  Returns:
-
-  void
-
-  *----------------------------------------------------------------------*/
+/**
+ * Add a new item to a list that is ordered by a comparison function. 
+ * This routine assumes that the list is properly ordered. 
+ *
+         * @param LThe list to operate on
+         * @param fPointer to a comparison function
+ * @param d     Pointer to data to pass to the comparison function
+ */
 
 void 
-pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
+pvl_insert_ordered(pvl_list L,pvl_comparef f,void *d)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-
     struct pvl_elem_t *P;
@@ -305,3 +242,3 @@ pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
@@ -313,3 +250,3 @@ pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
     { 
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
@@ -320,3 +257,3 @@ pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
     { 
-        pvl_push(l,d);
+        pvl_push(L,d);
         return;
@@ -331,3 +268,3 @@ pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
         {
-            pvl_insert_before(l,P,d);
+            pvl_insert_before(L,P,d);
             return;
@@ -337,31 +274,17 @@ pvl_insert_ordered(pvl_list l,pvl_comparef f,void *d)
     /* badness, choke */
-
+#ifndef lint
     assert(0);
-
+#endif
 }
 
-/*----------------------------------------------------------------------
-  Function: void  pvl_insert_after(pvl_list l,pvl_elem p,void *d)
-
-  Purpose:
-
-  Add a new item after the referenced element. 
-
-  Parameters:
-
-          lThe list to operate on 
-          pThe list element to add the item after
-          dPointer to the item to add. 
-
-  Returns:
-
-  void
-
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Add a new item after the referenced element. 
+         * @param LThe list to operate on 
+         * @param PThe list element to add the item after
+         * @param dPointer to the item to add. 
+ */
 
 void 
-pvl_insert_after(pvl_list l,pvl_elem p,void *d)
+pvl_insert_after(pvl_list L,pvl_elem P,void *d)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-    struct pvl_elem_t *P = (struct pvl_elem_t *)p;
     struct pvl_elem_t *E = 0;
@@ -372,3 +295,3 @@ pvl_insert_after(pvl_list l,pvl_elem p,void *d)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
@@ -390,23 +313,13 @@ pvl_insert_after(pvl_list l,pvl_elem p,void *d)
 
-/*----------------------------------------------------------------------
-  Function: void pvl_insert_before(pvl_list l,pvl_elem p,void *d)
-
-  Purpose:
-
-  Add an item after a referenced item
-
-  Parameters:
-
-          lThe list to operate on
-          pThe list element to add the item before
-          dPointer to the data to be added. 
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Add an item after a referenced item
+ *
+         * @param LThe list to operate on
+         * @param PThe list element to add the item before
+         * @param dPointer to the data to be added. 
+ */
 
 void 
-pvl_insert_before(pvl_list l,pvl_elem p,void *d)
+pvl_insert_before(pvl_list L,pvl_elem P,void *d)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-    struct pvl_elem_t *P = (struct pvl_elem_t *)p;
     struct pvl_elem_t *E = 0;
@@ -417,3 +330,3 @@ pvl_insert_before(pvl_list l,pvl_elem p,void *d)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
@@ -435,25 +348,15 @@ pvl_insert_before(pvl_list l,pvl_elem p,void *d)
 
-/*----------------------------------------------------------------------
-  Function: void pvl_remove(pvl_list l,pvl_elem e)
- 
-  Purpose:
-
-  Remove the referenced item from the list
-
-  This routine will free the element, but not the data item that the
-  element contains. 
-
-  Parameters:
-
-          lThe list to operate on
-          eThe element to remove. 
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Remove the referenced item from the list.
+ *
+ * This routine will free the element, but not the data item that the
+ * element contains. 
+ *
+         * @param LThe list to operate on
+         * @param EThe element to remove. 
+ */
 
 void* 
-pvl_remove(pvl_list l,pvl_elem e)
+pvl_remove(pvl_list L,pvl_elem E)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-    struct pvl_elem_t *E = (struct pvl_elem_t *)e;
     void* data;
@@ -506,24 +409,15 @@ pvl_remove(pvl_list l,pvl_elem e)
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem pvl_find(pvl_list l,pvl_findf f,void* v)
-
-  Purpose:
-
-  Return a pointer to data that satisfies a function
-
-  This routine will interate through the entire list and call the
-  find function for each item. It will break and return a pointer to the
-  data that causes the find function to return 1.
-
-  Parameters:
-
-          lThe list to operate on
-          fPointer to the find function
-          vPointer to constant data to pass into the function
-
-  Returns:
-
-  Pointer to the element that the find function found. 
-
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Return a pointer to data that satisfies a function.
+ *
+ * This routine will interate through the entire list and call the
+ * find function for each item. It will break and return a pointer to the
+ * data that causes the find function to return 1.
+ *
+         * @param lThe list to operate on
+         * @param fPointer to the find function
+         * @param vPointer to constant data to pass into the function
+ * 
+ * @return Pointer to the element that the find function found. 
+ */
 
@@ -547,21 +441,13 @@ pvl_find(pvl_list l,pvl_findf f,void* v)
 }
-/*----------------------------------------------------------------------
-  Function: void*  pvl_find_next(pvl_list l,pvl_findf f,void* v)
-
-  Purpose:
-
-  Like pvl_find(), but continues the search where the last find() or
-  find_next() left off
 
-  Parameters:
-
-          lThe list to operate on
-          fPointer to the find function
-          vPointer to constant data to pass into the function
-
-  Returns:
-
-  Pointer to the element that the find function found. 
-
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Like pvl_find(), but continues the search where the last find() or
+ * find_next() left off.
+ *
+         * @param lThe list to operate on
+         * @param fPointer to the find function
+         * @param vPointer to constant data to pass into the function
+ * 
+ * @return Pointer to the element that the find function found. 
+ */
 
@@ -587,13 +473,6 @@ pvl_find_next(pvl_list l,pvl_findf f,void* v)
 
-/*----------------------------------------------------------------------
-  Function: void pvl_clear(pvl_list l)
-
-  Purpose:
-  
-  Remove the all the elements in the list. The does not free the data items
-  the elements hold. 
-
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Remove the all the elements in the list. The does not free
+ * the data items the elements hold.
+ */
 
@@ -617,17 +496,10 @@ pvl_clear(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function: int pvl_count(pvl_list l)
-
-  Purpose:
-
-  Returns the number of items in the list. 
 
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Returns the number of items in the list. 
+ */
 
 int 
-pvl_count(pvl_list l)
+pvl_count(pvl_list L)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-
     return L->count;
@@ -636,16 +508,9 @@ pvl_count(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem  pvl_next(pvl_elem e)
- 
-  Purpose: 
-  Returns a pointer to the given element 
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Returns a pointer to the given element 
+ */
 
 pvl_elem 
-pvl_next(pvl_elem e)
+pvl_next(pvl_elem E)
 {
-    struct pvl_elem_t *E = (struct pvl_elem_t *)e;
-
     if (E == 0){
@@ -657,17 +522,10 @@ pvl_next(pvl_elem e)
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem  pvl_prior(pvl_elem e)
 
-  Purpose:
-
-  Returns a pointer to the element previous to the element given. 
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Returns a pointer to the element previous to the element given. 
+ */
 
 pvl_elem 
-pvl_prior(pvl_elem e)
+pvl_prior(pvl_elem E)
 {
-    struct pvl_elem_t *E = (struct pvl_elem_t *)e;
-
     return (pvl_elem)E->prior;
@@ -675,16 +533,10 @@ pvl_prior(pvl_elem e)
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem  pvl_head(pvl_list l )
- 
-  Purpose:
-  
-  Returns a pointer to the first item in the list. 
 
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Returns a pointer to the first item in the list. 
+ */
+
 pvl_elem 
-pvl_head(pvl_list l )
+pvl_head(pvl_list L )
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
-
     return (pvl_elem)L->head;
@@ -692,15 +544,8 @@ pvl_head(pvl_list l )
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem  pvl_tail(pvl_list l)
- 
-  Purpose:
-
-  Returns a pointer to the last item in the list. 
-
-  Returns:
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Returns a pointer to the last item in the list. 
+ */
 pvl_elem 
-pvl_tail(pvl_list l)
+pvl_tail(pvl_list L)
 {
-    struct pvl_list_t *L = (struct pvl_list_t *)l;
     return (pvl_elem)L->tail;
@@ -708,19 +553,7 @@ pvl_tail(pvl_list l)
 
-/*----------------------------------------------------------------------
-  Function:
- 
-
-  Purpose:
-
-
-  Returns:
-  *----------------------------------------------------------------------*/
-
 #ifndef PVL_USE_MACROS
 void* 
-pvl_data(pvl_elem e)
+pvl_data(pvl_elem E)
 {
-    struct pvl_elem_t *E = (struct pvl_elem_t *)e;
-  
-    if ( e == 0){
+    if ( E == 0){
         return 0;
@@ -732,19 +565,9 @@ pvl_data(pvl_elem e)
 
-/*----------------------------------------------------------------------
-  Function: void  pvl_apply(pvl_list l,pvl_applyf f, void *v)
- 
-  Purpose:
-
-  Call a function for every item in the list. 
-
-  Paramters: 
-
-          lThe list to operate on
-          fPointer to the function to call
-          vData to pass to the function on every iteration
-
-  Returns:
-
-  void
-  *----------------------------------------------------------------------*/
+/**
+ * @brief Call a function for every item in the list. 
+ *
+         * @param lThe list to operate on
+         * @param fPointer to the function to call
+         * @param vData to pass to the function on every iteration
+ */