1 files changed, 158 insertions, 335 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
@@ -12,54 +12,47 @@
 
 #include "pvl.h"
 #include <errno.h>
 #include <assert.h>
 #include <stdlib.h>
 
-
-
-/*
+/**
   struct pvl_list_t
 
   The list structure. This is the hanlde for the entire list 
 
   This type is also private. Use pvl_list instead 
 
   */
 
 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;
 
 
 
 
-/* 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 
+ */
 
 int pvl_elem_count = 0;
 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. 
+ */
 
 pvl_list 
 pvl_newlist()
 {
     struct pvl_list_t *L;
 
@@ -86,35 +79,26 @@ pvl_free(pvl_list l)
 
    pvl_clear(l);
 
    free(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)
 {
     struct pvl_elem_t *E;
 
@@ -129,31 +113,22 @@ pvl_new_element(void *d, pvl_elem next,pvl_elem prior)
     E->next = next;
     E->prior = prior;
 
     return (pvl_elem)E;
 }
 
-/*----------------------------------------------------------------------
-  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);
 
     if (E->next != 0)
     {
         /* Link the head node to it */
         E->next->prior = E;
@@ -169,59 +144,43 @@ pvl_unshift(pvl_list l,void *d)
         L->tail = E;
     }
 
     L->count++;
 }
 
-/*----------------------------------------------------------------------
-  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)
     {
         return 0;
     }
 
-    return pvl_remove(l,(void*)L->head);
+    return pvl_remove(L,(void*)L->head);
 
 }
 
-/*----------------------------------------------------------------------
-  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);
 
     /* These are done in pvl_new_element
        E->next = 0;
        E->prior = L->tail;
     */
@@ -239,141 +198,105 @@ pvl_push(pvl_list l,void *d)
     L->tail = E;
 
     L->count++;
 
 }
 
-/*----------------------------------------------------------------------
-  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)
     {
         return 0;
     }
 
-    return pvl_remove(l,(void*) L->tail);;
+    return pvl_remove(L,(void*) L->tail);;
 
 }
 
 
-/*----------------------------------------------------------------------
-  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;
 
     L->count++;
 
     /* Empty list, add to head */
 
     if(L->head == 0)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
     }
 
     /* smaller than head, add to head */
 
     if ( ((*f)(d,L->head->d)) <= 0)
     { 
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
     }
 
     /* larger than tail, add to tail */
     if ( (*f)(d,L->tail->d) >= 0)
     { 
-        pvl_push(l,d);
+        pvl_push(L,d);
         return;
     }
 
 
     /* Search for the first element that is smaller, and add before it */
     
     for (P=L->head; P != 0; P = P->next)
     {
         if ( (*f)(P->d,d) >= 0)
         {
-            pvl_insert_before(l,P,d);
+            pvl_insert_before(L,P,d);
             return;
         }
     }
 
     /* 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;
 
     L->count++;
 
     if (P == 0)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
     }
 
     if ( P == L->tail)
     {
         E = pvl_new_element(d,0,P);
@@ -385,40 +308,30 @@ pvl_insert_after(pvl_list l,pvl_elem p,void *d)
         E = pvl_new_element(d,P->next,P);
         E->next->prior  = E;
         E->prior->next = E;
     }
 }
 
-/*----------------------------------------------------------------------
-  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;
 
     L->count++;
 
     if (P == 0)
     {
-        pvl_unshift(l,d);
+        pvl_unshift(L,d);
         return;
     }
 
     if ( P == L->head)
     {
         E = pvl_new_element(d,P,0);
@@ -430,35 +343,25 @@ pvl_insert_before(pvl_list l,pvl_elem p,void *d)
         E = pvl_new_element(d,P,P->prior);
         E->prior->next = E;
         E->next->prior = E;
     }
 }
 
-/*----------------------------------------------------------------------
-  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;
 
     if (E == L->head)
     {
         if (E->next != 0)
         {
@@ -501,34 +404,25 @@ pvl_remove(pvl_list l,pvl_elem e)
     free(E);
 
     return data;
 
 }
 
-/*----------------------------------------------------------------------
-  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. 
+ */
 
 pvl_elem
 pvl_find(pvl_list l,pvl_findf f,void* v)
 {
     pvl_elem e;
     
@@ -542,31 +436,23 @@ pvl_find(pvl_list l,pvl_findf f,void* v)
         }
     }
     
     return 0;
 
 }
-/*----------------------------------------------------------------------
-  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. 
+ */
 
 pvl_elem
 pvl_find_next(pvl_list l,pvl_findf f,void* v)
 {
     
     pvl_elem e;
@@ -582,23 +468,16 @@ pvl_find_next(pvl_list l,pvl_findf f,void* v)
     }
 
     return 0;
 
 }
 
-/*----------------------------------------------------------------------
-  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.
+ */
 
 void 
 pvl_clear(pvl_list l)
 {
     pvl_elem e = pvl_head(l);
     pvl_elem next;
@@ -612,144 +491,88 @@ pvl_clear(pvl_list l)
         next = pvl_next(e);
         pvl_remove(l,e);
         e = next;
     }
 }
 
-/*----------------------------------------------------------------------
-  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;
 }
 
 
-/*----------------------------------------------------------------------
-  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){
         return 0;
     }
 
     return (pvl_elem)E->next;
 }
 
-/*----------------------------------------------------------------------
-  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;
 }
 
-/*----------------------------------------------------------------------
-  Function: pvl_elem  pvl_head(pvl_list l )
- 
-  Purpose:
   
-  Returns a pointer to the first item in the list. 
+/**
+ * @brief Returns a pointer to the first item in the list. 
+ */
 
-  Returns:
-  *----------------------------------------------------------------------*/
 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;
 }
 
-/*----------------------------------------------------------------------
-  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;
 }
 
-/*----------------------------------------------------------------------
-  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;
     }
 
     return E->d;
 }
 #endif
 
-/*----------------------------------------------------------------------
-  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
+ */
 
 void 
 pvl_apply(pvl_list l,pvl_applyf f, void *v)
 {
     pvl_elem e;