Mercurial > hg > ucx / changeset

--- a/ucx/list.h	Mon Jul 22 13:45:49 2013 +0200
+++ b/ucx/list.h	Mon Jul 22 14:51:52 2013 +0200
@@ -119,16 +119,48 @@
 UcxList *ucx_list_append(UcxList *list, void *data);
 UcxList *ucx_list_prepend(UcxList *list, void *data);
 UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
-UcxList *ucx_list_last(const UcxList *list);
+/**
+ * Returns the first element of a list.
+ * 
+ * If the argument is the list pointer, it is directly returned. Otherwise
+ * this function traverses to the first element of the list and returns the
+ * list pointer.
+ * 
+ * @param elem one element of the list
+ * @return the first element of the list, the specified element is a member of
+ */
+UcxList *ucx_list_first(const UcxList *elem);
+/**
+ * Returns the last element of a list.
+ * 
+ * If the argument has no successor, it is the last element and therefore
+ * directly returned. Otherwise this function traverses to the last element of
+ * the list and returns it.
+ * 
+ * @param elem one element of the list
+ * @return the last element of the list, the specified element is a member of
+ */
+UcxList *ucx_list_last(const UcxList *elem);
 UcxList *ucx_list_get(const UcxList *list, int index);
 ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
 size_t ucx_list_size(const UcxList *list);
-ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
-int ucx_list_contains(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
+ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
+int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
 
 UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
 
-UcxList *ucx_list_first(const UcxList *list);
+/**
+ * Removes an element from the list.
+ * 
+ * If the first element is removed, the list pointer changes. So it is
+ * <i>highly recommended</i> to <i>always</i> update the pointer by calling
+ * <code>mylist = ucx_list_remove(mylist, myelem);</code>.
+ * 
+ * @param list the list from which the element shall be removed
+ * @param element the element to removed
+ * @return returns the updated list pointer or <code>NULL</code>, if the list
+ * is now empty
+ */
 UcxList *ucx_list_remove(UcxList *list, UcxList *element);
 
 #ifdef	__cplusplus