hermet pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=ff5cc5d988006616406a65b8119ea6499b7b8bf6
commit ff5cc5d988006616406a65b8119ea6499b7b8bf6 Author: Bryce Harrington <[email protected]> Date: Thu Jul 26 20:04:46 2018 +0900 eina: Add doxygen in/out tags for inlist and iterator Reviewers: segfaultxavi Subscribers: segfaultxavi, cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6686 --- src/lib/eina/eina_inlist.h | 122 +++++++++++++++++++++++-------------------- src/lib/eina/eina_iterator.h | 32 ++++++------ 2 files changed, 80 insertions(+), 74 deletions(-) diff --git a/src/lib/eina/eina_inlist.h b/src/lib/eina/eina_inlist.h index 25260d1afa..0d20286639 100644 --- a/src/lib/eina/eina_inlist.h +++ b/src/lib/eina/eina_inlist.h @@ -430,8 +430,8 @@ struct _Eina_Inlist * check of @a new_l prev and next pointers is done, so it's safe * to have them uninitialized. * - * @param in_list Existing list head or @c NULL to create a new list. - * @param in_item New list node, must not be @c NULL. + * @param[in,out] in_list Existing list head or @c NULL to create a new list. + * @param[in] in_item New list node, must not be @c NULL. * * @return The new list head. Use it and not @a in_list anymore. */ @@ -449,8 +449,8 @@ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, * check of @a new_l prev and next pointers is done, so it's safe * to have them uninitialized. * - * @param in_list Existing list head or @c NULL to create a new list. - * @param in_item New list node, must not be @c NULL. + * @param[in,out] in_list Existing list head or @c NULL to create a new list. + * @param[in] in_item New list node, must not be @c NULL. * * @return The new list head. Use it and not @a in_list anymore. */ @@ -473,9 +473,9 @@ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, * will lead to problems. Giving NULL @a in_relative is the same as * eina_list_append(). * - * @param in_list Existing list head or @c NULL to create a new list. - * @param in_item New list node, must not be @c NULL. - * @param in_relative Reference node, @a in_item will be added after it. + * @param[in,out] in_list Existing list head or @c NULL to create a new list. + * @param[in] in_item New list node, must not be @c NULL. + * @param[in] in_relative Reference node, @a in_item will be added after it. * * @return The new list head. Use it and not @a list anymore. */ @@ -499,9 +499,9 @@ EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, * will lead to problems. Giving NULL @a in_relative is the same as * eina_list_prepend(). * - * @param in_list Existing list head or @c NULL to create a new list. - * @param in_item New list node, must not be @c NULL. - * @param in_relative Reference node, @a in_item will be added before it. + * @param[in,out] in_list Existing list head or @c NULL to create a new list. + * @param[in] in_item New list node, must not be @c NULL. + * @param[in] in_relative Reference node, @a in_item will be added before it. * * @return The new list head. Use it and not @a in_list anymore. */ @@ -521,8 +521,8 @@ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, * it will be different from @a list and the wrong new head will * be returned. * - * @param in_list Existing list head, must not be @c NULL. - * @param in_item Existing list node, must not be @c NULL. + * @param[in,out] in_list Existing list head, must not be @c NULL. + * @param[in] in_item Existing list node, must not be @c NULL. * * @return The new list head. Use it and not @a list anymore. */ @@ -535,8 +535,8 @@ EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, * @warning This is an expensive call and has O(n) cost, possibly * walking the whole list. * - * @param in_list Existing list to search @a in_item in, must not be @c NULL. - * @param in_item What to search for, must not be @c NULL. + * @param[in] in_list Existing list to search @a in_item in, must not be @c NULL. + * @param[in] in_item What to search for, must not be @c NULL. * * @return @a in_item if found, @c NULL if not. */ @@ -553,8 +553,8 @@ EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list, * done to confirm this, and giving nodes from different lists * will lead to problems. * - * @param list Existing list head or @c NULL to create a new list. - * @param item List node to move to beginning (head), must not be @c NULL. + * @param[in] list Existing list head or @c NULL to create a new list. + * @param[in] item List node to move to beginning (head), must not be @c NULL. * * @return The new list head. Use it and not @a list anymore. */ @@ -571,8 +571,8 @@ EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list, * done to confirm this, and giving nodes from different lists * will lead to problems. * - * @param list Existing list head or @c NULL to create a new list. - * @param item List node to move to end (tail), must not be @c NULL. + * @param[in] list Existing list head or @c NULL to create a new list. + * @param[in] item List node to move to end (tail), must not be @c NULL. * * @return The new list head. Use it and not @a list anymore. */ @@ -582,7 +582,7 @@ EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list, /** * @brief Gets the first list node in the list. * - * @param list The list to get the first list node from. + * @param[in] list The list to get the first list node from. * @return The first list node in the list. * * This function returns the first list node in the list @p list. If @@ -598,7 +598,7 @@ static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE /** * @brief Gets the last list node in the list. * - * @param list The list to get the last list node from. + * @param[in] 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 @@ -614,7 +614,7 @@ static inline Eina_Inlist *eina_inlist_last(const Eina_Inlist *list) EINA_PURE E /** * @brief Gets the count of the number of items in a list. * - * @param list The list whose count to return. + * @param[in] 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 @@ -630,7 +630,7 @@ EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_ /** * @brief Returns a new iterator associated to @a list. * - * @param in_list The list. + * @param[in] in_list The list. * @return A new iterator. * * This function returns a newly allocated iterator associated to @p @@ -651,7 +651,7 @@ EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MA /** * @brief Returns a new accessor associated to a list. * - * @param in_list The list. + * @param[in] in_list The list. * @return A new accessor. * * This function returns a newly allocated accessor associated to @@ -665,11 +665,10 @@ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MA /** * @brief Inserts a new node into a sorted list. * - * @param list The given linked list, @b must be sorted. - * @param item List node to insert, must not be @c NULL. - * @param func The function called for the sort. + * @param[in,out] list The given linked list, @b must be sorted. + * @param[in] item List node to insert, must not be @c NULL. + * @param[in] func The function called for the sort. * @return A list pointer. - * @since 1.1.0 * * This function inserts item into a linked list assuming it was * sorted and the result will be sorted. If @p list is @c NULL, item @@ -682,6 +681,8 @@ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MA * 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). + * + * @since 1.1.0 */ EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item, Eina_Compare_Cb func) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; @@ -689,6 +690,7 @@ EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item * @brief Creates state with valid data in it. * * @return A valid Eina_Inlist_Sorted_State. + * * @since 1.1.0 * * See eina_inlist_sorted_state_insert() for more information. @@ -698,9 +700,10 @@ EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void); /** * @brief Forces an Eina_Inlist_Sorted_State to match the content of a list. * - * @param state The state to update - * @param list The list to match + * @param[in,out] state The state to update + * @param[in] list The list to match * @return The number of item in the actually in the list + * * @since 1.1.0 * * See eina_inlist_sorted_state_insert() for more information. This function is @@ -712,7 +715,8 @@ EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inl /** * @brief Frees an Eina_Inlist_Sorted_State. * - * @param state The state to destroy + * @param[in,out] state The state to destroy + * * @since 1.1.0 * * See eina_inlist_sorted_state_insert() for more information. @@ -722,10 +726,10 @@ EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state); /** * @brief Inserts a new node into a sorted list. * - * @param list The given linked list, @b must be sorted. - * @param item list node to insert, must not be @c NULL. - * @param func The function called for the sort. - * @param state The current array for initial dichotomic search + * @param[in,out] list The given linked list, @b must be sorted. + * @param[in] item list node to insert, must not be @c NULL. + * @param[in] func The function called for the sort. + * @param[in,out] state The current array for initial dichotomic search * @return A list pointer. * @since 1.1.0 * @@ -754,8 +758,8 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list, /** * @brief Sorts a list according to the ordering func will return. * - * @param head The list handle to sort. - * @param func A function pointer that can handle comparing the list data + * @param[in,out] head The list handle to sort. + * @param[in] func A function pointer that can handle comparing the list data * nodes. * @return the new head of list. * @@ -800,15 +804,15 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /* These two macros are helpers for the _FOREACH ones, don't use them */ /** * @def _EINA_INLIST_OFFSET - * @param ref The reference to be used. + * @param[in,out] ref The reference to be used. */ #define _EINA_INLIST_OFFSET(ref) ((char *)&(ref)->__in_list - (char *)(ref)) #if !defined(__cplusplus) /** * @def _EINA_INLIST_CONTAINER - * @param ref The reference to be used. - * @param ptr The pointer to be used. + * @param[in,out] ref The reference to be used. + * @param[out] ptr The pointer to be used. */ #define _EINA_INLIST_CONTAINER(ref, ptr) (void *)((char *)(ptr) - \ _EINA_INLIST_OFFSET(ref)) @@ -823,9 +827,9 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_FOREACH - * @param list The list to iterate on. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * @param[in,out] list The list to iterate on. + * @param[out] it The pointer to the list item, i.e. a pointer to each + * item that is part of the list. */ #define EINA_INLIST_FOREACH(list, it) \ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); it; \ @@ -833,13 +837,14 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_FOREACH_SAFE - * @param list The list to iterate on. - * @param list2 Auxiliary Eina_Inlist variable so we can save the pointer to the - * next element, allowing us to free/remove the current one. Note that this - * macro is only safe if the next element is not removed. Only the current one - * is allowed to be removed. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * @param[in,out] list The list to iterate on. + * @param[out] list2 Auxiliary Eina_Inlist variable so we can save the + * pointer to the next element, allowing us to free/remove + * the current one. Note that this macro is only safe if the + * next element is not removed. Only the current one is + * allowed to be removed. + * @param[out] it The pointer to the list item, i.e. a pointer to each + * item that is part of the list. */ #define EINA_INLIST_FOREACH_SAFE(list, list2, it) \ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? EINA_INLIST_GET(it)->next : NULL; \ @@ -848,9 +853,9 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_REVERSE_FOREACH - * @param list The list to traverse in reverse order. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * @param[in,out] list The list to traverse in reverse order. + * @param[out] it The pointer to the list item, i.e. a pointer to each + * item that is part of the list. */ #define EINA_INLIST_REVERSE_FOREACH(list, it) \ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list->last) : NULL); \ @@ -858,10 +863,11 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_REVERSE_FOREACH_FROM - * @param list The last list to traverse in reverse order. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * @param[in,out] list The last list to traverse in reverse order. + * @param[in] it The pointer to the list item, i.e. a pointer to each + * item that is part of the list. * @see EINA_INLIST_REVERSE_FOREACH() + * * @since 1.8 * * EINA_INLIST_REVERSE_FOREACH() starts from last list of the given list. @@ -873,9 +879,9 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_FREE - * @param list The list to free. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * @param[in,out] list The list to free. + * @param[in] it The pointer to the list item, i.e. a pointer to each item + * that is part of the list. * * NOTE: it is the duty of the body loop to properly remove the item from the * inlist and free it. This function will turn into a infinite loop if you diff --git a/src/lib/eina/eina_iterator.h b/src/lib/eina/eina_iterator.h index d26b2cc9dc..6c33db1a63 100644 --- a/src/lib/eina/eina_iterator.h +++ b/src/lib/eina/eina_iterator.h @@ -199,7 +199,7 @@ struct _Eina_Iterator /** * @brief Frees an iterator. * - * @param iterator The iterator to free. + * @param[in,out] iterator The iterator to free. * * This function frees @p iterator if it is not @c NULL; */ @@ -209,7 +209,7 @@ EAPI void eina_iterator_free(Eina_Iterator *iterator); /** * @brief Returns the container of an iterator. * - * @param iterator The iterator. + * @param[in] iterator The iterator. * @return The container which created the iterator. * * This function returns the container which created @p iterator. If @@ -220,8 +220,8 @@ EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NON /** * @brief Returns the value of the current element and go to the next one. * - * @param iterator The iterator. - * @param data The data of the element. + * @param[in,out] iterator The iterator. + * @param[out] data The data of the element. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * This function returns the value of the current element pointed by @@ -236,9 +236,9 @@ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator, /** * @brief Iterates over the container and execute a callback on each element. * - * @param iterator The iterator. - * @param callback The callback called on each iteration. - * @param fdata The data passed to the callback. + * @param[in,out] iterator The iterator. + * @param[in] callback The callback called on each iteration. + * @param[in] fdata The data passed to the callback. * * This function iterates over the elements pointed by @p iterator, * beginning with the current element. For each element, the callback @@ -255,7 +255,7 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, /** * @brief Locks the container of the iterator. * - * @param iterator The iterator. + * @param[in,out] iterator The iterator. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * If the container of the @p iterator permits it, it will be locked. When a @@ -271,7 +271,7 @@ EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); /** * @brief Unlocks the container of the iterator. * - * @param iterator The iterator. + * @param[in,out] iterator The iterator. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * If the container of the @p iterator permits it and was previously @@ -288,7 +288,7 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) * @brief Creates an Eina_Iterator that iterates through a * NUL-terminated C array. * - * @param array The NUL-terminated array + * @param[in] array The NUL-terminated array * * You can create it like this: * int array[] = {1, 2, 3, 4}; @@ -303,10 +303,10 @@ EAPI Eina_Iterator* eina_carray_iterator_new(void** array) EINA_ARG_NONNULL(1) E /** * @brief Creates a new iterator which which iterates through all elements with are accepted by the filter callback * - * @param original the iterator the use as original set - * @param filter if the callback returns true the element from the original set is taken into the the new set. - * @param free_cb when the iterator is gone this callback will be called with data as argument - * @param data the data which is passed to the filter callback + * @param[in] original the iterator the use as original set + * @param[in] filter if the callback returns true the element from the original set is taken into the the new set. + * @param[in] free_cb when the iterator is gone this callback will be called with data as argument + * @param[in] data the data which is passed to the filter callback * * The iterator is filtered while it is being iterated. * The original iterator you pass in here is is then owned and will be freed once the the new iterator is freed. @@ -319,8 +319,8 @@ EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_ * @def EINA_ITERATOR_FOREACH * @brief Definition for the macro to iterate over all elements easily. * - * @param itr The iterator to use. - * @param data Where to store * data, must be a pointer support getting + * @param[in,out] itr The iterator to use. + * @param[out] data Where to store * data, must be a pointer support getting * its address since * eina_iterator_next() requires a pointer * to pointer! * --
