Enlightenment CVS committal

Author  : ncn
Project : e17
Module  : libs/evas

Dir     : e17/libs/evas/src/lib/data


Modified Files:
        evas_hash.c evas_list.c 


Log Message:
More documentation, simplification and grouping.  Some of these changes are themselves 
going to require polishing, but the docs are now a little bit more organised.
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/evas/src/lib/data/evas_hash.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -3 -r1.7 -r1.8
--- evas_hash.c 12 Aug 2004 12:14:01 -0000      1.7
+++ evas_hash.c 16 Aug 2004 05:13:25 -0000      1.8
@@ -224,9 +224,16 @@
 }
 
 /**
+ * @defgroup Evas_Hash_General_Group Hash General Functions
+ *
+ * Miscellaneous functions that operate on hash objects.
+ */
+
+/**
  * Retrieves the number of buckets available in the given hash table.
  * @param hash The given hash table.
  * @return @c 256 if @p hash is not @c NULL.  @c 0 otherwise.
+ * @ingroup Evas_Hash_General_Group
  */
 int
 evas_hash_size(Evas_Hash *hash)
@@ -235,7 +242,10 @@
    return 256;
 }
 
-/** @todo Complete documenting evas_hash.c */
+/**
+ * @todo Complete polishing documentation for evas_hash.c. The
+ * functions' docs may be grouped, but they need some simplification.
+ */
 
 /**
  * Free an entire hash table
@@ -254,6 +264,7 @@
  * evas_hash_free(hash);
  * hash = NULL;
  * @endcode
+ * @ingroup Evas_Hash_General_Group
  */
 void
 evas_hash_free(Evas_Hash *hash)
@@ -308,6 +319,7 @@
  *   free(hash_fn_data);
  * }
  * @endcode
+ * @ingroup Evas_Hash_General_Group
  */
 void
 evas_hash_foreach(Evas_Hash *hash, Evas_Bool (*func) (Evas_Hash *hash, const char 
*key, void *data, void *fdata), const void *fdata)
@@ -358,6 +370,7 @@
  *     printf("My Data inserted and successfully found.\n");
  *   }
  * @endcode
+ * @ingroup Evas_Hash_General_Group
  */
 int
 evas_hash_alloc_error(void)
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/evas/src/lib/data/evas_list.c,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -3 -r1.5 -r1.6
--- evas_list.c 24 Mar 2004 07:23:51 -0000      1.5
+++ evas_list.c 16 Aug 2004 05:13:25 -0000      1.6
@@ -5,20 +5,17 @@
 static int _evas_list_alloc_error = 0;
 
 /**
- * Append a data pointer to a linked list
- * @param list The list handle to append @p data too
- * @param data The data pointer to append to list @p list
- * @return A new list handle to replace the old one
- * 
- * This function appends the data pointed to by @p data to the end of the linked
- * list @p list, and returns a new list pointer to replace the old one. An
- * empty list should start as a NULL pointer.
- * 
- * In the event of a memory allocation failure, the old list pointer will be
- * returned and the application should use evas_list_alloc_error() to determine
- * if the allocation failed and sensibly recover from this condition.
+ * @defgroup Evas_List_Data_Group Linked List Creation Functions
+ *
+ * Functions that add data to an Evas_List.
+ */
+
+/**
+ * Appends the given data to the given linked list.
  * 
- * Example:
+ * The following example code demonstrates how to ensure that the
+ * given data has been successfully appended.
+ *
  * @code
  * Evas_List *list = NULL;
  * extern void *my_data;
@@ -30,6 +27,14 @@
  *     exit(-1);
  *   }
  * @endcode
+ *
+ * @param   list The given list.  If @c NULL is given, then a new list
+ *               is created.
+ * @param   data The data to append.
+ * @return  A new list pointer that should be used in place of the one
+ *          given to this function if successful.  Otherwise, the old
+ *          pointer is returned.
+ * @ingroup Evas_List_Data_Group
  */
 Evas_List *
 evas_list_append(Evas_List *list, const void *data)
@@ -79,18 +84,10 @@
 }
 
 /**
- * Prepend a data pointer to a linked list
- * @param list The list handle to prepend @p data too
- * @param data The data pointer to prepend to list @p list
- * @return A new list handle to replace the old one
- * 
- * This function prepends the data pointed to by @p data to the start of the linked
- * list @p list, and returns a new list pointer to replace the old one. An
- * empty list should start as a NULL pointer.
- * 
- * In the event of a memory allocation failur, the old list pointer will be
- * returned and the application should use evas_list_alloc_error() to determine
- * if the allocation failed and sensibly recover from this condition.
+ * Prepends the given data to the given linked list.
+ *
+ * The following example code demonstrates how to ensure that the
+ * given data has been successfully prepended.
  * 
  * Example:
  * @code
@@ -104,6 +101,13 @@
  *     exit(-1);
  *   }
  * @endcode
+ *
+ * @param   list The given list.
+ * @param   data The given data.
+ * @return  A new list pointer that should be used in place of the one
+ *          given to this function, if successful.  Otherwise, the old
+ *          pointer is returned.
+ * @ingroup Evas_List_Data_Group
  */
 Evas_List *
 evas_list_prepend(Evas_List *list, const void *data)
@@ -135,27 +139,15 @@
 }
 
 /**
- * Append a data pointer to a linked list after the memeber specified
- * @param list The list handle to append @p data too
- * @param data The data pointer to append to list @p list after @p relative
- * @param relative The data pointer after which to insert @p data
- * @return A new list handle to replace the old one
- * 
- * This function appends the data pointed to by @p data after the position in
- * of the list member whose data pointer is @p relative, in the list @p list, 
- * and returns a new list pointer to replace the old one. An empty list 
- * should start as a NULL pointer.
- * 
- * If no member in the list has a data pointer of @p relative, the item is
- * appended to the very end of the list. If there are multiple members of the
- * list with the data pointer @p relative, the @p data item is inserted after
- * the first instance of the member @p relative in the list.
- * 
- * In the event of a memory allocation failure, the old list pointer will be
- * returned and the application should use evas_list_alloc_error() to determine
- * if the allocation failed and sensibly recover from this condition.
+ * Inserts the given data into the given linked list after the specified data.
+ *
+ * If @p relative is not in the list, @p data is appended to the end of the
+ * list.  If there are multiple instances of @p relative in the list, 
+ * @p data is inserted after the first instance.
  * 
- * Example:
+ * The following example code demonstrates how to ensure that the
+ * given data has been successfully inserted.
+ *
  * @code
  * Evas_List *list = NULL;
  * extern void *my_data;
@@ -174,6 +166,14 @@
  *     exit(-1);
  *   }
  * @endcode
+ *
+ * @param   list The given linked list.
+ * @param   data The given data.
+ * @param   relative The data to insert after.
+ * @return  A new list pointer that should be used in place of the one
+ *          given to this function if successful.  Otherwise, the old pointer
+ *          is returned.
+ * @ingroup Evas_List_Data_Group
  */
 Evas_List *
 evas_list_append_relative(Evas_List *list, const void *data, const void *relative)
@@ -218,22 +218,17 @@
  * @param data The data pointer to prepend to list @p list before @p relative
  * @param relative The data pointer before which to insert @p data
  * @return A new list handle to replace the old one
+
+ * Inserts the given data into the given linked list before the member
+ * specified.
+ *
+ * If @p relative is not in the list, @p data is prepended to the
+ * start of the list.  If there are multiple instances of @p relative
+ * in the list, @p data is inserted before the first instance.
  * 
- * This function prepends the data pointed to by @p data before the position in
- * of the list member whose data pointer is @p relative, in the list @p list, 
- * and returns a new list pointer to replace the old one. An empty list 
- * should start as a NULL pointer.
- * 
- * If no member in the list has a data pointer of @p relative, the item is
- * prepended to the very start of the list. If there are multiple members of the
- * list with the data pointer @p relative, the @p data item is inserted before
- * the first instance of the member @p relative in the list.
- * 
- * In the event of a memory allocation failure, the old list pointer will be
- * returned and the application should use evas_list_alloc_error() to determine
- * if the allocation failed and sensibly recover from this condition.
- * 
- * Example:
+ * The following code example demonstrates how to ensure that the
+ * given data has been successfully inserted.
+ *
  * @code
  * Evas_List *list = NULL;
  * extern void *my_data;
@@ -252,6 +247,14 @@
  *     exit(-1);
  *   }
  * @endcode
+ *
+ * @param   list The given linked list.
+ * @param   data The given data.
+ * @param   relative The data to insert before.
+ * @return  A new list pointer that should be used in place of the one
+ *          given to this function if successful.  Otherwise the old pointer
+ *          is returned.
+ * @ingroup Evas_List_Data_Group
  */
 Evas_List *
 evas_list_prepend_relative(Evas_List *list, const void *data, const void *relative)
@@ -295,24 +298,21 @@
 }
 
 /**
- * Remove a specified member from a list
- * @param list The list handle to remove @p data from
- * @param data The memebr to find and remove
- * @return A new list handle to replace the old one
- * 
- * Calling this function finds the first instance of the member whose data
- * pointer is @p data in the list @p list and removed that member from the
- * the list. An empty list should start as a NULL pointer.
- * 
- * If no member is found that matches, nothing is done.
- * 
- * Example:
- * @code
- * extern Evas_List *list;
- * extern void *my_data;
+ * @defgroup Evas_List_Remove_Group Linked List Remove Functions
+ *
+ * Functions that remove data from linked lists.
+ */
+
+/**
+ * Removes the first instance of the specified data from the given list.
  * 
- * list = evas_list_remove(list, my_data);
- * @endcode
+ * If the specified data is not in the given list, nothing is done.
+ *
+ * @param   list The given list.
+ * @param   data The specified data.
+ * @return  A new list pointer that should be used in place of the one 
+ *          passed to this functions.
+ * @ingroup Evas_List_Remove_Group
  */
 Evas_List *
 evas_list_remove(Evas_List *list, const void *data)
@@ -328,6 +328,8 @@
 }
 
 /**
+ * Removes the specified data
+ * 
  * Remove a specified member from a list
  * @param list The list handle to remove @p remove_list from
  * @param remove_list The list node which is to be removed
@@ -351,6 +353,7 @@
  *       }
  *   }
  * @endcode
+ * @ingroup Evas_List_Remove_Group
  */
 Evas_List *
 evas_list_remove_list(Evas_List *list, Evas_List *remove_list)
@@ -378,6 +381,12 @@
 }
 
 /**
+ * @defgroup Evas_List_Find_Group Linked List Find Functions
+ *
+ * Functions that find specified data in a linked list.
+ */
+
+/**
  * Find a member of a list and return the member
  * @param list The list handle to search for @p data
  * @param data The data pointer to find in the list @p list
@@ -397,6 +406,7 @@
  *     printf("Found member %p\n", my_data);
  *   }
  * @endcode
+ * @ingroup Evas_List_Find_Group
  */
 void *
 evas_list_find(Evas_List *list, const void *data)
@@ -433,6 +443,7 @@
  *     printf("Found member %p\n", found_node->data);
  *   }
  * @endcode
+ * @ingroup Evas_List_Find_Group
  */
 Evas_List *
 evas_list_find_list(Evas_List *list, const void *data)
@@ -459,6 +470,7 @@
  * 
  * list = evas_list_free(list);
  * @endcode
+ * @ingroup Evas_List_Remove_Group
  */
 Evas_List *
 evas_list_free(Evas_List *list)
@@ -475,6 +487,12 @@
 }
 
 /**
+ * @defgroup Evas_List_Traverse_Group Linked List Traverse Functions
+ * 
+ * Functions that you can use to traverse a linked list.
+ */
+
+/**
  * Get the last list node in the list
  * @param list The list to get the last list node from
  * @return The last list node in the list @p list
@@ -497,6 +515,7 @@
  *     printf("%p\n", l->data);
  *   }
  * @endcode
+ * @ingroup Evas_List_Traverse_Group
  */
 Evas_List *
 evas_list_last(Evas_List *list)
@@ -524,6 +543,7 @@
  *     printf("%p\n", l->data);
  *   }
  * @endcode
+ * @ingroup Evas_List_Traverse_Group
  */
 Evas_List *
 evas_list_next(Evas_List *list)
@@ -552,6 +572,7 @@
  *     printf("%p\n", l->data);
  *   }
  * @endcode
+ * @ingroup Evas_List_Traverse_Group
  */
 Evas_List *
 evas_list_prev(Evas_List *list)
@@ -561,6 +582,12 @@
 }
 
 /**
+ * @defgroup Evas_List_General_Group Linked List General Functions
+ *
+ * Miscellaneous functions that work on linked lists.
+ */
+
+/**
  * Get the list node data member
  * @param list The list node to get the data member of
  * @return The data member from the list node @p list
@@ -579,6 +606,7 @@
  *     printf("%p\n", evas_list_data(l));
  *   }
  * @endcode
+ * @ingroup Evas_List_General_Group
  */
 void *
 evas_list_data(Evas_List *list)
@@ -604,6 +632,7 @@
  * 
  * printf("The list has %i members\n", evas_list_count(list));
  * @endcode
+ * @ingroup Evas_List_General_Group
  */
 int
 evas_list_count(Evas_List *list)
@@ -632,6 +661,7 @@
  * if (data)
  *   printf("Element number %i has data %p\n", number, data);
  * @endcode
+ * @ingroup Evas_List_Find_Group
  */
 void *
 evas_list_nth(Evas_List *list, int n)
@@ -667,6 +697,7 @@
  * if (nth_list)
  *   printf("Element number %i has data %p\n", number, nth_list->data);
  * @endcode
+ * @ingroup Evas_List_Find_Group
  */
 Evas_List *
 evas_list_nth_list(Evas_List *list, int n)
@@ -683,6 +714,12 @@
 }
 
 /**
+ * @defgroup Evas_List_Ordering_Group Linked List Ordering Functions
+ *
+ * Functions that change the ordering of data in a linked list.
+ */
+
+/**
  * Reverse all the elements in the list
  * @param list The list to reverse
  * @return The list after it has been reversed
@@ -696,6 +733,7 @@
  * 
  * list = evas_list_reverse(list);
  * @endcode
+ * @ingroup Evas_List_Ordering_Group
  */
 Evas_List *
 evas_list_reverse(Evas_List *list)
@@ -798,6 +836,7 @@
  *     exit(-1);
  *   }
  * @endcode
+ * @ingroup Evas_List_Ordering_Group
  */
 Evas_List *
 evas_list_sort(Evas_List *list, int size, int (*func)(void *, void *))
@@ -847,6 +886,7 @@
  *     exit(-1);
  *   }
  * @endcode
+ * @ingroup Evas_List_General_Group
  */
 int
 evas_list_alloc_error(void)




-------------------------------------------------------
SF.Net email is sponsored by Shop4tech.com-Lowest price on Blank Media
100pk Sonic DVD-R 4x for only $29 -100pk Sonic DVD+R for only $33
Save 50% off Retail on Ink & Toner - Free Shipping and Free Gift.
http://www.shop4tech.com/z/Inkjet_Cartridges/9_108_r285
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs

Reply via email to