From 6ba44f9006e252deeeb179c14095c591d6727ce2 Mon Sep 17 00:00:00 2001 From: Bryce Harrington Date: Fri, 25 May 2018 10:19:20 -0700 Subject: [PATCH] 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 --- 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 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. + * This function returns a newly allocated accessor associated with + * @p array. Accessors differ from iterators in that they permit + * random access. + * + * @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