From cda565a38ea3dce2d1089901d1506731c14c7bc5 Mon Sep 17 00:00:00 2001
From: Vincent Torri <vincent.torri@gmail.com>
Date: Thu, 29 Jan 2009 23:16:23 +0000
Subject: [PATCH]  * more doc in the tutorial of the array data type  * minor
 formatting

SVN revision: 38853
---
 legacy/eina/src/include/eina_array.h        |  8 +--
 legacy/eina/src/include/eina_inline_array.x | 16 +++--
 legacy/eina/src/lib/eina_array.c            | 77 ++++++++++++++++++++-
 3 files changed, 88 insertions(+), 13 deletions(-)

diff --git a/legacy/eina/src/include/eina_array.h b/legacy/eina/src/include/eina_array.h
index 7d15445bce..ae83b6edd9 100644
--- a/legacy/eina/src/include/eina_array.h
+++ b/legacy/eina/src/include/eina_array.h
@@ -111,10 +111,10 @@ EAPI Eina_Accessor *eina_array_accessor_new (const Eina_Array *array) EINA_MALLO
  * the following example:
  *
  * @code
- * Eina_Array          *array;
- * char                *item;
- * Eina_Array_Iterator  iterator;
- * unsigned int         i;
+ * Eina_Array         *array;
+ * char               *item;
+ * Eina_Array_Iterator iterator;
+ * unsigned int        i;
  *
  * // array is already filled,
  * // its elements are just duplicated strings,
diff --git a/legacy/eina/src/include/eina_inline_array.x b/legacy/eina/src/include/eina_inline_array.x
index 41bf0a8016..f13b9f1e9d 100644
--- a/legacy/eina/src/include/eina_inline_array.x
+++ b/legacy/eina/src/include/eina_inline_array.x
@@ -52,9 +52,10 @@ EAPI Eina_Bool eina_array_grow(Eina_Array *array);
  *
  * 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 an allocation is necessary and
- * fails, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY is
- * set. Otherwise, #EINA_TRUE is returned.
+ * invalid, the program may crash. If @p data is @c NULL, or if an
+ * allocation is necessary and fails, #EINA_FALSE is returned and
+ * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, #EINA_TRUE is
+ * returned.
  */
 static inline Eina_Bool
 eina_array_push(Eina_Array *array, const void *data)
@@ -74,10 +75,11 @@ eina_array_push(Eina_Array *array, const void *data)
  * @param array The array.
  * @return The retrieved data.
  *
- * This function removes the last data of @p array and returns it. 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 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.
  */
 static inline void *
 eina_array_pop(Eina_Array *array)
diff --git a/legacy/eina/src/lib/eina_array.c b/legacy/eina/src/lib/eina_array.c
index 9a39acd3f0..71ac83b7f5 100644
--- a/legacy/eina/src/lib/eina_array.c
+++ b/legacy/eina/src/lib/eina_array.c
@@ -60,10 +60,83 @@
  * following command:
  *
  * @code
- * gcc -Wall -o my_exe my_source.c `pkg-config --cflags --libs eina`
+ * gcc -o my_bin my_source.c `pkg-config --cflags --libs eina-0`
  * @endcode
  *
- * Then, an array must created with eina_array_new().
+ * Then, an array must created with eina_array_new(). That function
+ * takes an integer as parameter, which is the count of pointers to
+ * add when increasing the array size. Once the array is not used
+ * anymore, it must be destroyed with eina_array_free().
+ *
+ * To append data at the end of the array, the function
+ * eina_array_push() must be used. To remove the data at the end of
+ * the array, eina_array_pop() must be used. Once the array is filled,
+ * one can check its elements by iterating over it. A while loop and
+ * eina_array_data_get() can be used, or else one can use the
+ * predefined macro EINA_ARRAY_ITER_NEXT(). To free all the elements,
+ * a while loop can be used with eina_array_count_get(). Here is an
+ * example of use:
+ *
+ * @code
+ * #include <stdlib.h>
+ * #include <stdio.h>
+ * #include <string.h>
+ *
+ * #include <eina_array.h>
+ *
+ * int main(void)
+ * {
+ *     const char *strings[] = {
+ *         "first string",
+ *         "second string",
+ *         "third string",
+ *         "fourth string"
+ *     };
+ *     Eina_Array         *array;
+ *     char               *item;
+ *     Eina_Array_Iterator iterator;
+ *     unsigned int        i;
+ *
+ *     if (!eina_array_init())
+ *     {
+ *         printf ("Error during the initialization of eina_error module\n");
+ *         return EXIT_FAILURE;
+ *     }
+ *
+ *     array = eina_array_new(16);
+ *     if (!array)
+ *         goto shutdown_array;
+ *
+ *     for (i = 0; i < 4; i++)
+ *     {
+ *         eina_array_push(array, strdup(strings[i]));
+ *     }
+ *
+ *     printf("array count: %d\n", eina_array_count_get(array));
+ *     EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
+ *     {
+ *         printf("item #%d: %s\n", i, item);
+ *     }
+ *
+ *     while (eina_array_count_get(array))
+ *     {
+ *         void *data;
+ *
+ *         data = eina_array_pop(array);
+ *         free(data);
+ *     }
+ *
+ *     eina_array_free(array);
+ *     eina_array_shutdown();
+ *
+ *     return EXIT_SUCCESS;
+ *
+ *   shutdown_array:
+ *     eina_array_shutdown();
+ *
+ *     return EXIT_FAILURE;
+ * }
+ * @endcode
  *
  * To be continued
  */