cedric pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=6ba44f9006e252deeeb179c14095c591d6727ce2
commit 6ba44f9006e252deeeb179c14095c591d6727ce2
Author: Bryce Harrington <br...@osg.samsung.com>
Date: Fri May 25 10:19:20 2018 -0700
eina: Improve eina_array function documentation
Summary:
Define return values when errors occur. Eliminate use of the term
'vector' to avoid confusion with eina_vector. Cleanup grammar
throughout.
Reviewers: cedric, Hermet
Reviewed By: Hermet
Subscribers: #committers, zmike
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D6043
Reviewed-by: Cedric BAIL <ced...@osg.samsung.com>
---
src/lib/eina/eina_array.h | 161 +++++++++++++++++++++++-----------------------
1 file changed, 80 insertions(+), 81 deletions(-)
diff --git a/src/lib/eina/eina_array.h b/src/lib/eina/eina_array.h
index 20ee31fdcc..09d8290352 100644
--- a/src/lib/eina/eina_array.h
+++ b/src/lib/eina/eina_array.h
@@ -49,7 +49,7 @@
* Before we can start using any array function we need to initialize eina:
* @until eina_init
*
- * So now to actually create our array. The only interesting thing here is the
+ * So now to actually create our array. The interesting thing here is the
* argument given to the eina_array_new() function. This argument sets how fast
* the array grows.
* @until array_new
@@ -101,8 +101,8 @@
* @skip #include
* @until Eina.h
*
- * This the callback we are going to use to decide which strings stay on the
- * array and which will be removed. We use something simple, but this can be as
+ * This is the callback we are going to use to decide which strings stay on the
+ * array and which will be removed. We use something simple, but this can be
as
* complex as you like:
* @until }
*
@@ -144,10 +144,10 @@
* @brief These functions provide array management.
*
* The Array data type in Eina is designed to have very fast access to
- * its data (compared to the Eina @ref Eina_List_Group). On the other hand,
- * data can be added or removed only at the end of the array. To insert
- * data at any position, the Eina @ref Eina_List_Group is the correct container
- * to use.
+ * its data (compared to the Eina @ref Eina_List_Group). On the other
+ * hand, data can be added or removed only at the end of the array. To
+ * insert data at arbitrary positions, the Eina @ref Eina_List_Group is
+ * the correct container to use.
*
* To use the array data type, eina_init() must be called before any
* other array functions. When no more eina array functions are used,
@@ -156,9 +156,9 @@
* An array must be created with eina_array_new(). It allocates all
* the necessary data for an array. When not needed anymore, an array
* is freed with eina_array_free(). This frees the memory used by the
Eina_Array
- * itself, but does not free any memory used to store the data of each
element.
+ * itself, but does not free any memory used to store the data of each element.
* To free that memory you must iterate over the array and free each data
element
- * individually. A convenient way to do that is by using
#EINA_ARRAY_ITER_NEXT.
+ * individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT.
* An example of that pattern is given in the description of @ref
EINA_ARRAY_ITER_NEXT.
*
* @warning Functions do not check if the used array is valid or not. It's up
to
@@ -171,15 +171,12 @@
* eina_array_data_get(). The number of elements can be retrieved with
* eina_array_count().
*
- * Eina_Array is different from a conventional C array in a number of ways,
most
- * importantly they grow and shrink dynamically, this means that if you add an
- * element to a full array it grows and that when you remove an element from an
- * array it @b may shrink.
- *
- * Allocating memory is expensive, so when the array needs to grow it
allocates
- * enough memory to hold @p step additional elements, not just the element
- * currently being added. Similarly if you remove elements, it won't free
space
- * until you have removed @p step elements.
+ * An Eina_Array differs most notably from a conventional C array in that it
can
+ * grow and shrink dynamically as elements are added and removed.
+ * Since allocating memory is expensive, when the array needs to grow it adds
+ * enough memory to hold @p step additional elements, not just the element
+ * currently being added. Similarly when elements are removed, it won't
deallocate
+ * until @p step elements are removed.
*
* The following image illustrates how an Eina_Array grows:
*
@@ -214,7 +211,7 @@
/**
* @typedef Eina_Array
- * Type for a generic vector.
+ * Type for a generic one-dimensional linear data structure.
*/
typedef struct _Eina_Array Eina_Array;
@@ -233,10 +230,10 @@ struct _Eina_Array
#define EINA_ARRAY_VERSION 1
int version; /**< Should match EINA_ARRAY_VERSION used when
compiled your apps, provided for ABI compatibility */
- void **data; /**< Pointer to a vector of pointer to payload */
- unsigned int total; /**< Number of allocated slots in the vector */
- unsigned int count; /**< Number of slots in the vector that actually point
to data */
- unsigned int step; /**< Number of slots to grow or shrink the vector */
+ void **data; /**< Pointer to a C array of pointers to payloads */
+ unsigned int total; /**< Number of allocated slots in @p data */
+ unsigned int count; /**< Number of used slots in @p data that point to
valid payloads */
+ unsigned int step; /**< Number of slots to grow or shrink @p data */
EINA_MAGIC
};
@@ -248,7 +245,7 @@ struct _Eina_Array
* @return @c NULL on failure, non @c NULL otherwise.
*
* This function creates a new array. When adding an element, the array
- * allocates @p step elements. When that buffer is full, then adding
+ * allocates @p step elements. When that buffer is full, adding
* another element will increase the buffer by @p step elements again.
*
* This function return a valid array on success, or @c NULL if memory
@@ -261,12 +258,12 @@ EAPI Eina_Array *eina_array_new(unsigned int step)
EINA_WARN_UNUSED_RESULT EINA_
*
* @param[in] array The array to free.
*
- * This function frees @p array. It calls first eina_array_flush() then
- * frees the memory of the pointer. It does not free the memory
- * allocated for the elements of @p array. To free them, walk the array with
- * #EINA_ARRAY_ITER_NEXT.
+ * This function finalizes @p array by flushing (see
+ * eina_array_flush()), and then freeing the memory of the pointer. It
+ * does not free the memory allocated for the elements of @p array. To
+ * free them, walk the array with #EINA_ARRAY_ITER_NEXT.
*/
-EAPI void eina_array_free(Eina_Array *array);
+EAPI void eina_array_free(Eina_Array *array);
/**
* @brief Sets the step of an array.
@@ -285,24 +282,24 @@ EAPI void eina_array_step_set(Eina_Array *array,
unsigned int sizeof_eina_array,
unsigned int step) EINA_ARG_NONNULL(1);
/**
- * @brief Cleans an array.
+ * @brief Clears an array of its elements, without deallocating memory.
*
* @param[in,out] array The array to clean.
*
- * This function sets the count member of @p array to 0, however it doesn't
free
- * any space. This is particularly useful if you need to empty the array and
- * add lots of elements quickly. For performance reasons, there is no check of
- * @p array. If it is @c NULL or invalid, the program may crash.
+ * This function sets the @p array's member count to 0 without freeing
+ * memory. This facilitates emptying an array and quickly refilling it
+ * with new elements. For performance reasons, there is no check of @p
+ * array. If it is @c NULL or invalid, the program may crash.
*/
static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @brief Flushes an array.
+ * @brief Clears an array's elements and deallocates the memory.
*
* @param[in,out] array The array to flush.
*
- * This function sets the count and total members of @p array to 0,
- * frees and set to NULL its data member. For performance reasons,
+ * This function sets the count and total members of @p array to 0, and
+ * frees its data member and sets it to NULL. For performance reasons,
* there is no check of @p array. If it is @c NULL or invalid, the
* program may crash.
*/
@@ -329,32 +326,30 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array,
void *gdata) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Appends a data to an array.
+ * @brief Appends a data item to an array.
*
* @param[in,out] array The array.
* @param[in] data The data to add.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @return #EINA_TRUE on success, #EINA_FALSE if allocation is necessary
+ * and fails or if @p data is @c NULL.
*
* This function appends @p data to @p array. For performance
* reasons, there is no check of @p array. If it is @c NULL or
- * invalid, the program may crash. If @p data is @c NULL, or if an
- * allocation is necessary and fails, #EINA_FALSE is returned
- * Otherwise, #EINA_TRUE is returned.
+ * invalid, the program may crash.
*/
static inline Eina_Bool eina_array_push(Eina_Array *array,
const void *data) EINA_ARG_NONNULL(1,
2);
/**
- * @brief Removes the last data of an array.
+ * @brief Removes the last data item in an array.
*
* @param[in,out] array The array.
- * @return The retrieved data.
+ * @return The retrieved data, or @c NULL if there are no remaining items.
*
- * This function removes the last data of @p array, decreases the count
- * of @p array and returns the data. For performance reasons, there
- * is no check of @p array. If it is @c NULL or invalid, the program
- * may crash. If the count member is less or equal than 0, @c NULL is
- * returned.
+ * This function removes the last data item from @p array, decreases the
+ * length of @p array and returns the data item. For performance reasons,
+ * there is no check of @p array, so if it is @c NULL or invalid, the
+ * program may crash.
*/
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
@@ -367,7 +362,8 @@ static inline void *eina_array_pop(Eina_Array *array)
EINA_ARG_NONNULL(1);
*
* This function returns the data at the position @p idx in @p
* array. For performance reasons, there is no check of @p array or @p
- * idx. If it is @c NULL or invalid, the program may crash.
+ * idx. If @p array is @c NULL or invalid, or if @p idx is larger than
+ * the array's size, the program may crash.
*/
static inline void *eina_array_data_get(const Eina_Array *array,
unsigned int idx)
EINA_ARG_NONNULL(1);
@@ -378,15 +374,17 @@ static inline void *eina_array_data_get(const
Eina_Array *array,
* @param[in] idx The position of the data to set.
* @param[in] data The data to set.
*
- * This function sets the data at the position @p idx in @p
- * array to @p data, this effectively replaces the previously held data, you
- * must therefore get a pointer to it first if you need to free it. For
- * performance reasons, there is no check of @p array or @p idx. If it is @c
- * NULL or invalid, the program may crash.
+ * This function sets the data at the position @p idx in @p array to @p
+ * data, this effectively replaces the previously held data, you must
+ * therefore get a pointer to it first if you need to free it. For
+ * performance reasons, there is no check of @p array or @p idx. If @p
+ * array is @c NULL or invalid, or if @p idx is larger than the array's
+ * size, the program may crash.
*/
static inline void eina_array_data_set(const Eina_Array *array,
unsigned int idx,
const void *data)
EINA_ARG_NONNULL(1);
+
/**
* @deprecated use eina_array_count()
* @brief Returns the number of elements in an array.
@@ -395,7 +393,7 @@ static inline void eina_array_data_set(const
Eina_Array *array,
* @return The number of elements.
*
* This function returns the number of elements in @p array (array->count). For
- * performance reasons, there is no check of @p array. If it is
+ * performance reasons, there is no check of @p array, so if it is
* @c NULL or invalid, the program may crash.
*
*/
@@ -408,7 +406,7 @@ static inline unsigned int eina_array_count_get(const
Eina_Array *array) EINA_AR
* @return The number of elements.
*
* This function returns the number of elements in @p array (array->count). For
- * performance reasons, there is no check of @p array. If it is
+ * performance reasons, there is no check of @p array, so if it is
* @c NULL or invalid, the program may crash.
*/
static inline unsigned int eina_array_count(const Eina_Array *array)
EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@@ -417,12 +415,14 @@ static inline unsigned int eina_array_count(const
Eina_Array *array) EINA_ARG_NO
* @brief Gets a new iterator associated with an array.
*
* @param[in] array The array.
- * @return A new iterator.
+ * @return A new iterator, or @c NULL if @p array is @c NULL or has no
+ * items, or if memory could not be allocated.
*
- * This function returns a newly allocated iterator associated to
- * @p array. If @p array is @c NULL or the count member of @p array is
- * less or equal than 0, this function returns @c NULL. If the memory can
- * not be allocated, @c NULL is returned. Otherwise, a valid iterator is
returned.
+ * This function allocates a new iterator associated with @p array.
+ * Use EINA_ARRAY_ITER_NEXT() to iterate through the array's data items
+ * in order of entry.
+ *
+ * @see Eina_Iterator_Group
*/
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@@ -430,27 +430,28 @@ EAPI Eina_Iterator *eina_array_iterator_new(const
Eina_Array *array) EINA
* @brief Gets a new accessor associated with an array.
*
* @param[in] array The array.
- * @return A new accessor.
+ * @return A new accessor, or @c NULL if @p array is @c NULL or has no
+ * items, or if memory could not be allocated.
+ *
+ * This function returns a newly allocated accessor associated with
+ * @p array. Accessors differ from iterators in that they permit
+ * random access.
*
- * This function returns a newly allocated accessor associated to
- * @p array. If @p array is @c NULL or the count member of @p array is
- * less or equal than 0, this function returns @c NULL. If the memory can
- * not be allocated, @c NULL is returned. Otherwise, a valid accessor is
- * returned.
+ * @see Eina_Accessor_Group
*/
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Provides a safe way to iterate over an array.
+ * @brief Iterates over an array using a callback function.
*
* @param[in] array The array to iterate over.
- * @param[in] cb The callback to call for each item.
+ * @param[in] cb The callback to invoke for each item.
* @param[in] fdata The user data to pass to the callback.
* @return #EINA_TRUE if it successfully iterated all items of the array.
*
- * This function provides a safe way to iterate over an array. @p cb should
- * return #EINA_TRUE as long as you want the function to continue iterating.
- * If @p cb returns #EINA_FALSE, iterations will stop and the function will
also
+ * This function iterates over an array in order, calling @p cb for each
+ * item. @p cb should return #EINA_TRUE if the loop should continue, or
+ * #EINA_FALSE to exit the loop, in which case eina_array_foreach() will
* return #EINA_FALSE.
*/
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
@@ -458,20 +459,18 @@ static inline Eina_Bool eina_array_foreach(Eina_Array
*array,
void *fdata);
/**
* @def EINA_ARRAY_ITER_NEXT
- * @brief Definition for the macro to iterate over an array easily.
+ * @brief Iterates through an array's elements.
*
* @param[in] array The array to iterate over.
* @param[out] index The integer number that is increased while iterating.
* @param[out] item The data
- * @param[in,out] iterator The iterator
+ * @param[in,out] iterator The #Eina_Array_Iterator.
*
- * This macro allows the iteration over @p array in an easy way. It
- * iterates from the first element to the last one. @p index is an
- * integer that increases from 0 to the number of elements. @p item is
- * the data of each element of @p array, so it is a pointer to a type
- * chosen by the user. @p iterator is of type #Eina_Array_Iterator.
+ * This macro iterates over @p array in order, increasing @p index from
+ * the first to last element and setting @p item to each element's data
+ * item in turn.
*
- * This macro can be used for freeing the data of an array, like in
+ * This macro can be used for freeing the data of an array, such as
* the following example:
*
* @code
--
