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 <cedric@osg.samsung.com>

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
+ * 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
+ * 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,
+ * its data (compared to the Eina @ref Eina_List_Group). On the other
- * data can be added or removed only at the end of the array. To insert
+ * hand, data can be added or removed only at the end of the array. To
- * data at any position, the Eina @ref Eina_List_Group is the correct container
+ * insert data at arbitrary positions, the Eina @ref Eina_List_Group is
- * to use.
+ * 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
+ * An Eina_Array differs most notably from a conventional C array in that it can
- * importantly they grow and shrink dynamically, this means that if you add an
+ * grow and shrink dynamically as elements are added and removed.
- * element to a full array it grows and that when you remove an element from an
+ * Since allocating memory is expensive, when the array needs to grow it adds
- * array it @b may shrink.
+ * enough memory to hold @p step additional elements, not just the element
- *
+ * currently being added. Similarly when elements are removed, it won't deallocate
- * Allocating memory is expensive, so when the array needs to grow it allocates 
+ * until @p step elements are removed.
- * 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. 
  *
  * 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 */
+   void       **data;  /**< Pointer to a C array of pointers to payloads */
-   unsigned int total; /**< Number of allocated slots in the vector */
+   unsigned int total; /**< Number of allocated slots in @p data */
-   unsigned int count; /**< Number of slots in the vector that actually point to 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 the vector */
+   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
+ * This function finalizes @p array by flushing (see
- * frees the memory of the pointer. It does not free the memory
+ * eina_array_flush()), and then freeing the memory of the pointer. It
- * allocated for the elements of @p array. To free them, walk the array with
+ * does not free the memory allocated for the elements of @p array. To
- * #EINA_ARRAY_ITER_NEXT.
+ * 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
+ * This function sets the @p array's member count to 0 without freeing
- * any space. This is particularly useful if you need to empty the array and
+ * memory.  This facilitates emptying an array and quickly refilling it
- * add lots of elements quickly. For performance reasons, there is no check of
+ * with new elements.  For performance reasons, there is no check of @p
- * @p array. If it is @c NULL or invalid, the program may crash.
+ * 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,
+ * This function sets the count and total members of @p array to 0, and
- * frees and set to NULL its data member. For performance reasons,
+ * 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
+ * invalid, the program may crash.
- * allocation is necessary and fails, #EINA_FALSE is returned
- * Otherwise, #EINA_TRUE is returned.
  */
 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
+ * This function removes the last data item from @p array, decreases the
- * of @p array and returns the data. For performance reasons, there
+ * length of @p array and returns the data item. For performance reasons,
- * is no check of @p array. If it is @c NULL or invalid, the program
+ * there is no check of @p array, so if it is @c NULL or invalid, the
- * may crash. If the count member is less or equal than 0, @c NULL is
+ * program may crash.
- * returned.
  */
 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
+ * This function sets the data at the position @p idx in @p array to @p
- * array to @p data, this effectively replaces the previously held data, you
+ * data, this effectively replaces the previously held data, you must
- * must therefore get a pointer to it first if you need to free it. For
+ * 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
+ * performance reasons, there is no check of @p array or @p idx. If @p
- * NULL or invalid, the program may crash.
+ * 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
+ * This function allocates a new iterator associated with @p array.
- * @p array. If @p array is @c NULL or the count member of @p array is
+ * Use EINA_ARRAY_ITER_NEXT() to iterate through the array's data items
- * less or equal than 0, this function returns @c NULL. If the memory can
+ * in order of entry.
- * not be allocated, @c NULL is returned. Otherwise, a valid iterator is returned.
+ *
+ * @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
+ * This function returns a newly allocated accessor associated with
- * @p array. If @p array is @c NULL or the count member of @p array is
+ * @p array.  Accessors differ from iterators in that they permit
- * less or equal than 0, this function returns @c NULL. If the memory can
+ * random access.
- * 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
+ * This function iterates over an array in order, calling @p cb for each
- * return #EINA_TRUE as long as you want the function to continue iterating.
+ * item.  @p cb should return #EINA_TRUE if the loop should continue, or
- * If @p cb returns #EINA_FALSE, iterations will stop and the function will also
+ * #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
+ * This macro iterates over @p array in order, increasing @p index from
- * iterates from the first element to the last one. @p index is an
+ * the first to last element and setting @p item to each element's data
- * integer that increases from 0 to the number of elements. @p item is
+ * item in turn.
- * 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 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