From 75f98349b4efc0b30d71ca1e789b5f7b8357d62e Mon Sep 17 00:00:00 2001 From: gastal Date: Wed, 6 Jul 2011 14:50:33 +0000 Subject: [PATCH] Eina: Improvements to eina_list's documentation. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@61088 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/examples/eina_list_03.c | 2 + src/examples/eina_list_04.c | 7 +- src/include/eina_inline_list.x | 78 ------------------ src/include/eina_list.h | 179 ++++++++++++++++++++++++++++++++++++++++- 4 files changed, 184 insertions(+), 82 deletions(-) diff --git a/src/examples/eina_list_03.c b/src/examples/eina_list_03.c index 15bf909..8e15b91 100644 --- a/src/examples/eina_list_03.c +++ b/src/examples/eina_list_03.c @@ -27,6 +27,8 @@ main(int argc, char **argv) l = eina_list_data_find_list(list, "aerilon"); eina_list_data_set(l, "aquarius"); + printf("size: %d\n", eina_list_count(list)); + r_list = eina_list_reverse_clone(list); itr = eina_list_iterator_new(r_list); diff --git a/src/examples/eina_list_04.c b/src/examples/eina_list_04.c index e6526a1..c153c06 100644 --- a/src/examples/eina_list_04.c +++ b/src/examples/eina_list_04.c @@ -21,8 +21,11 @@ main(int argc, char **argv) list = eina_list_append(list, eina_stringshare_add("Six")); list = eina_list_append(list, eina_stringshare_add("Sharon")); - EINA_LIST_FOREACH(list, l, list_data) - printf("%s\n", (const char*)list_data); + for(l = list; l; l = eina_list_next(l)) + printf("%s\n", (char*)l->data); + + for(l = eina_list_last(list); l; l = eina_list_prev(l)) + printf("%s\n", (char*)eina_list_data_get(l)); EINA_LIST_FREE(list, list_data) eina_stringshare_del(list_data); diff --git a/src/include/eina_inline_list.x b/src/include/eina_inline_list.x index 8325370..3397a1b 100644 --- a/src/include/eina_inline_list.x +++ b/src/include/eina_inline_list.x @@ -19,26 +19,6 @@ #ifndef EINA_LIST_INLINE_H_ #define EINA_LIST_INLINE_H_ -/** - * @addtogroup Eina_List_Group List - * - * @brief These functions provide list management. - * - * @{ - */ - -/** - * @brief 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. - * - * This function returns the last list node in the list @p list. If - * @p list is @c NULL or empty, @c NULL is returned. - * - * This is a order-1 operation (it takes the same short time - * regardless of the length of the list). - */ static inline Eina_List * eina_list_last(const Eina_List *list) { @@ -46,16 +26,6 @@ eina_list_last(const Eina_List *list) return list->accounting->last; } -/** - * @brief Get the next list node after the specified list node. - * - * @param list The list node to get the next list node from - * @return The next list node on success, @c NULL otherwise. - * - * This function returns the next list node after the current one in - * @p list. It is equivalent to list->next. If @p list is @c NULL or - * if no next list node exists, it returns @c NULL. - */ static inline Eina_List * eina_list_next(const Eina_List *list) { @@ -63,17 +33,6 @@ eina_list_next(const Eina_List *list) return list->next; } -/** - * @brief Get the previous list node before the specified list node. - * - * @param list The list node to get the previous list node from. - * @return The previous list node o success, @c NULL otherwise. - * if no previous list node exists - * - * This function returns the previous list node before the current one - * in @p list. It is equivalent to list->prev. If @p list is @c NULL or - * if no previous list node exists, it returns @c NULL. - */ static inline Eina_List * eina_list_prev(const Eina_List *list) { @@ -81,16 +40,6 @@ eina_list_prev(const Eina_List *list) return list->prev; } -/** - * @brief 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. - * - * This function returns the data member of the specified list node @p - * list. It is equivalent to list->data. If @p list is @c NULL, this - * function returns @c NULL. - */ static inline void * eina_list_data_get(const Eina_List *list) { @@ -98,17 +47,6 @@ eina_list_data_get(const Eina_List *list) return list->data; } -/** - * @brief Set the list node data member. - * - * @param list The list node to get the data member of. - * @param data The data member to the list node. - * @return The previous data value. - * - * This function set the data member @p data of the specified list node - * @p list. It returns the previous data of the node. If @p list is - * @c NULL, this function returns @c NULL. - */ static inline void * eina_list_data_set(Eina_List *list, const void *data) { @@ -119,18 +57,6 @@ eina_list_data_set(Eina_List *list, const void *data) return tmp; } -/** - * @brief Get the count of the number of items in a list. - * - * @param list The list whose count to return. - * @return The number of members in the list. - * - * This function returns how many members @p list contains. If the - * list is @c NULL, 0 is returned. - * - * NB: This is an order-1 operation and takes the same time regardless - * of the length of the list. - */ static inline unsigned int eina_list_count(const Eina_List *list) { @@ -138,8 +64,4 @@ eina_list_count(const Eina_List *list) return list->accounting->count; } -/** - * @} - */ - #endif /* EINA_LIST_INLINE_H_ */ diff --git a/src/include/eina_list.h b/src/include/eina_list.h index 7985081..2e5352c 100644 --- a/src/include/eina_list.h +++ b/src/include/eina_list.h @@ -168,7 +168,11 @@ * To replace an element in the list it is not necessary to remove it and then * add with the new value, it is possible to just change the value of a node: * @until aquarius - * + * + * We will now take a peek to see if the list still has the right number of + * elements: + * @until printf + * * Now that the list is in alphabetical order let's create a copy of it in * reverse order and print every element to see if worked as expected: * @until iterator_free @@ -202,7 +206,10 @@ * @skip #include * @until Sharon * - * The most common way of iterating over a list: + * This time we are going to iterate over our list in a different way: + * @until printf + * + * And now we are going to iterate over the list backwards: * @until printf * * And now we need to free up the memory allocated during creation of the list: @@ -257,6 +264,11 @@ * @ref eina_list_data_find), the @a list versions of these functions operate * on @ref Eina_List nodes. * + * @warning You must @b always use the pointer to the first element of the list + * as the list! + * @warning You must @b never use a pointer to an element in the middle of the + * list as the list! + * * Here are some examples of @ref Eina_List usage: * @li @ref list_01_example_page * @li @ref list_02_example_page @@ -351,6 +363,8 @@ struct _Eina_List_Accounting * exit(-1); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list(or NULL). */ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -382,6 +396,8 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E * exit(-1); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -423,6 +439,8 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) * exit(-1); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -443,6 +461,8 @@ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void * instance. On success, a new list pointer that should be used in * place of the one given to this function is returned. Otherwise, the * old pointer is returned. + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -484,6 +504,8 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const * exit(-1); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -504,6 +526,8 @@ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const voi * instance. On success, a new list pointer that should be used in * place of the one given to this function is returned. Otherwise, the * old pointer is returned. + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -528,6 +552,8 @@ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, cons * lists do not have O(1) access time, so walking to the correct node * can be costly, consider worst case to be almost O(n) pointer * dereference (list walk). + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; @@ -545,6 +571,8 @@ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare * @p list is @c NULL, @c NULL is returned, otherwise a new list * pointer that should be used in place of the one passed to this * function. + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -581,6 +609,8 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E * } * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -613,6 +643,8 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem * } * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -645,6 +677,8 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo * } * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list); @@ -670,6 +704,8 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov * printf("Found member %p\n", my_data); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -684,6 +720,8 @@ EAPI void *eina_list_data_find(const Eina_List *list, const void * first member whose data pointer is @p data. If it is found, the * list node containing the specified member is returned, otherwise * @c NULL is returned. + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -699,6 +737,8 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const * This function is a shortcut for doing the following: * to = eina_list_append(to, data); * from = eina_list_remove(from, data); + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data); @@ -713,6 +753,8 @@ EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void * This function is a shortcut for doing the following: * to = eina_list_append(to, data->data); * from = eina_list_remove_list(from, data); + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data); @@ -740,6 +782,10 @@ EAPI Eina_List *eina_list_free(Eina_List *list); * the @p list. The first element in the array is element number 0. If * the element number @p n does not exist, @c NULL is * returned. Otherwise, the data of the found element is returned. + * + * @note Worst case is O(n). + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; @@ -757,6 +803,10 @@ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) * greater than the count of elements in @p list minus 1, @c NULL is * returned. Otherwise the list node stored in the numbered element is * returned. + * + * @note Worst case is O(n). + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; @@ -774,6 +824,8 @@ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned in * @note @b in-place: this will change the given list, so you should * now point to the new list head that is returned by this function. * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_reverse_clone() * @see eina_list_iterator_reversed_new() */ @@ -793,6 +845,8 @@ EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_R * @note @b copy: this will copy the list and you should then * eina_list_free() when it is not required anymore. * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_reverse() * @see eina_list_clone() */ @@ -812,6 +866,8 @@ EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_W * @note @b copy: this will copy the list and you should then * eina_list_free() when it is not required anymore. * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_reverse_clone() */ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT; @@ -857,6 +913,8 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS * * list = eina_list_sort(list, eina_list_count(list), sort_cb); * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int size, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; @@ -875,6 +933,8 @@ EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int size, Ei * @note merge cost is O(n), being @b n the size of the smallest * list. This is due the need to fix accounting of that segment, * making count and last access O(1). + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT; @@ -913,6 +973,8 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI * * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb); * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; @@ -932,6 +994,7 @@ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *ri * * list does not exist anymore after the split. * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT; @@ -948,6 +1011,12 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela * than requested data, it is less than 0 and if it's bigger it's * greater than 0. It is the last value returned by func(). * @return the nearest node, NULL if not found. + * + * This function searches for a node containing @p data as it's data in @p list, + * if such a node exists it will be returned and @p result_cmp will be @p 0. If + * the data of no node in @p list is equal to @p data, the node with the nearest + * value to that will be returned and @p result_cmp will be the return value of + * @p func with @p data and the returned node's data as arguments. * * This function is useful for inserting an element in the list only in case it * isn't already present in the list, the naive way of doing this would be: @@ -983,6 +1052,8 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela * the correct node can be costly, consider worst case to be almost * O(n) pointer dereference (list walk). * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_search_sorted_list() * @see eina_list_sort() * @see eina_list_sorted_merge() @@ -1015,6 +1086,8 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li * time, so walking to the correct node can be costly, consider worst * case to be almost O(n) pointer dereference (list walk). * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_search_sorted() * @see eina_list_sort() * @see eina_list_sorted_merge() @@ -1050,6 +1123,8 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E * time, so walking to the correct node can be costly, consider worst * case to be almost O(n) pointer dereference (list walk). * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_search_sorted_list() * @see eina_list_sort() * @see eina_list_sorted_merge() @@ -1076,6 +1151,8 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C * that is for 1,000,000 elements list it may walk and compare * 1,000,000 nodes. * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_search_sorted_list() * @see eina_list_search_unsorted() */ @@ -1101,19 +1178,101 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, * that is for 1,000,000 elements list it may walk and compare * 1,000,000 nodes. * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_search_sorted() * @see eina_list_search_unsorted_list() */ EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data); +/** + * @brief 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. + * + * This function returns the last list node in the list @p list. If + * @p list is @c NULL or empty, @c NULL is returned. + * + * This is a order-1 operation (it takes the same short time + * regardless of the length of the list). + * + * @warning @p list must be a pointer to the first element of the list. + */ static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; +/** + * @brief Get the next list node after the specified list node. + * + * @param list The list node to get the next list node from + * @return The next list node on success, @c NULL otherwise. + * + * This function returns the next list node after the current one in + * @p list. It is equivalent to list->next. If @p list is @c NULL or + * if no next list node exists, it returns @c NULL. + * + * @warning @p list must be a pointer to the first element of the list. + */ static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; +/** + * @brief Get the previous list node before the specified list node. + * + * @param list The list node to get the previous list node from. + * @return The previous list node o success, @c NULL otherwise. + * if no previous list node exists + * + * This function returns the previous list node before the current one + * in @p list. It is equivalent to list->prev. If @p list is @c NULL or + * if no previous list node exists, it returns @c NULL. + * + * @warning @p list must be a pointer to the first element of the list. + */ static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; +/** + * @brief 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. + * + * This function returns the data member of the specified list node @p + * list. It is equivalent to list->data. If @p list is @c NULL, this + * function returns @c NULL. + * + * @warning @p list must be a pointer to the first element of the list. + */ static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; +/** + * @brief Set the list node data member. + * + * @param list The list node to get the data member of. + * @param data The data member to the list node. + * @return The previous data value. + * + * This function set the data member @p data of the specified list node + * @p list. It returns the previous data of the node. If @p list is + * @c NULL, this function returns @c NULL. + * + * @warning @p list must be a pointer to the first element of the list. + */ +static inline void *eina_list_data_set(Eina_List *list, const void *data) EINA_PURE; + +/** + * @brief Get the count of the number of items in a list. + * + * @param list The list whose count to return. + * @return The number of members in the list. + * + * This function returns how many members @p list contains. If the + * list is @c NULL, 0 is returned. + * + * NB: This is an order-1 operation and takes the same time regardless + * of the length of the list. + * + * @warning @p list must be a pointer to the first element of the list. + */ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; @@ -1133,6 +1292,8 @@ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is * returned. * + * @warning @p list must be a pointer to the first element of the list. + * * @warning if the list structure changes then the iterator becomes * invalid! That is, if you add or remove nodes this iterator * behavior is undefined and your program may crash! @@ -1158,6 +1319,8 @@ EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MA * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is * returned. * + * @warning @p list must be a pointer to the first element of the list. + * * @warning if the list structure changes then the iterator becomes * invalid! That is, if you add or remove nodes this iterator * behavior is undefined and your program may crash! @@ -1176,6 +1339,8 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list * less or equal than 0, this function returns NULL. If the memory can * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is * set. Otherwise, a valid accessor is returned. + * + * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; @@ -1211,6 +1376,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * a list, since it iterates over the list twice. * For an optimized algorithm, use EINA_LIST_FREE(). * + * @warning @p list must be a pointer to the first element of the list. + * * @warning Be careful when deleting list nodes. * If you remove the current node and continue iterating, * the code will fail because the macro will not be able @@ -1259,6 +1426,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * a list, since it iterates over the list twice. * For an optimized algorithm, use EINA_LIST_FREE(). * + * @warning @p list must be a pointer to the first element of the list. + * * @warning Be careful when deleting list nodes. * If you remove the current node and continue iterating, * the code will fail because the macro will not be able @@ -1308,6 +1477,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * list = eina_list_remove_list(list, l); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \ for (l = list, \ @@ -1354,6 +1525,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * list = eina_list_remove_list(list, l); * } * @endcode + * + * @warning @p list must be a pointer to the first element of the list. */ #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \ for (l = eina_list_last(list), \ @@ -1387,6 +1560,8 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * free(data); * @endcode * + * @warning @p list must be a pointer to the first element of the list. + * * @see eina_list_free() */ #define EINA_LIST_FREE(list, data) \ -- 2.7.4