Eina: Improvement to eina_iterator's documentation.

SVN revision: 61087

legacy/eina/src/include/eina_iterator.h

@@ -232,14 +232,15 @@ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
  * @brief Iterate over the container and execute a callback on each element.
  *
  * @param iterator The iterator.
- * @param cb The callback called on each iteration.
+ * @param callback The callback called on each iteration.
  * @param fdata The data passed to the callback.
  *
  * This function iterates over the elements pointed by @p iterator,
  * beginning from the current element. For Each element, the callback
  * @p cb is called with the data @p fdata. If @p iterator is @c NULL,
  * the function returns immediately. Also, if @p cb returns @c
- * EINA_FALSE, the iteration stops at that point.
+ * EINA_FALSE, the iteration stops at that point, if @p cb returns @c EINA_TRUE
+ * the iteration continues.
  */
 EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
                                 Eina_Each_Cb   callback,
@@ -252,10 +253,13 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
  * @param iterator The iterator.
  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
  *
- * If the container of the @p iterator permits it, it will be locked.
- * If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE is
- * returned, otherwise #EINA_TRUE is returned. If the container
- * is not lockable, it will return EINA_TRUE.
+ * If the container of the @p iterator permits it, it will be locked. When a
+ * container is locked calling eina_iterator_foreach() on it will return
+ * imediately. If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE
+ * is returned, otherwise #EINA_TRUE is returned. If the container isn't
+ * lockable, it will return EINA_TRUE.
+ *
+ * @warning None of the existing eina data structures are lockable.
  */
 EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
 
@@ -270,6 +274,8 @@ EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
  * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE
  * is returned. If the container is not lockable, it will return
  * EINA_TRUE.
+ *
+ * @warning None of the existing eina data structures are lockable.
  */
 EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
 
@@ -308,6 +314,9 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1)
  *    it will walk the list twice, but it serves as an example. For
  *    optimized version use EINA_LIST_FREE()
  *
+ * @warning The order in which the elements will be traversed depends on the
+ * underlying container and @b shouldn't be relied upon.
+ *
  * @warning unless explicitly stated in functions returning iterators,
  *    do not modify the iterated object while you walk it, in this
  *    example using lists, do not remove list nodes or you might