eina: Add a little more documentation for our examples

reference/c/eina/src/eina_array.c

@@ -6,9 +6,18 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina Array examples.
+ *
+ * These examples demonstrate how to work with eina_array data and methods.
+ * We use a simple array of strings to initialise our eina_array before
+ * performing various mutations and printing the results.
+ */
+
 static Eina_Array *
 _array_create()
 {
+   // some content to populate our array
    const char *names[] =
    {
       "helo", "hera", "starbuck", "kat", "boomer",
@@ -20,7 +29,8 @@ _array_create()
    Eina_Array *array;
    unsigned int i;
 
-   array = eina_array_new(20);
+   // set up an array with a growth step to give a little headroom
+   array = eina_array_new(25);
    for (i = 0; i < 20; i++)
      eina_array_push(array, strdup(names[i]));
 
@@ -33,6 +43,7 @@ static void _array_free(Eina_Array *array)
    char *item;
    unsigned int i;
 
+   // free each item in our array and then free the array itself
    EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
      free(item);
    eina_array_free(array);
@@ -41,6 +52,7 @@ static void _array_free(Eina_Array *array)
 static Eina_Bool
 _item_print(const void *container EINA_UNUSED, void *data, void *fdata EINA_UNUSED)
 {
+   // we know our content is just strings so we can simply printf the data
    printf("  %s\n", (char *)data);
    return EINA_TRUE;
 }
@@ -51,6 +63,7 @@ _item_keep(void *data, void *gdata EINA_UNUSED)
    const char *name;
    name = (const char *)data;
 
+   // let's keep any strings that are no more than 7 characters long
    if (strlen(name) <= 7)
       return EINA_TRUE;
 

reference/c/eina/src/eina_hash.c

@@ -6,6 +6,17 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina Hash examples.
+ *
+ * These examples demonstrate how to work with eina_hash data and methods.
+ *
+ * We have two main hash objects here, firstly an int keyed hash with some
+ * dummy content.
+ * The second example is that of a simple telephone book. The names are the
+ * string keys to the hash with phone numbers in the data field.
+ */
+
 static void
 _entry_free_cb(void *data)
 {
@@ -38,11 +49,13 @@ _hash_demo()
 
    hash = _hash_create();
 
+   // get an iterator of the keys so we can print a line per entry
    iter = eina_hash_iterator_key_new(hash);
 
    printf("Print contents of int hash\n");
    EINA_ITERATOR_FOREACH(iter, key)
    {
+      // look up the value for the key so we can print both
       value = eina_hash_find(hash, key);
       printf("  Item found with id %d has value %s\n", *key, value);
    }
@@ -52,6 +65,8 @@ _hash_demo()
    eina_hash_free(hash);
 }
 
+// here we begin the phone book example
+
 static void
 _phonebook_entry_print(const void *key, void *data)
 {
@@ -68,6 +83,7 @@ _phonebook_print(Eina_Hash *book)
    count = eina_hash_population(book);
    printf("Complete phone book (%d):\n", count);
 
+   // this iterator returns the key and value for each entry
    iter = eina_hash_iterator_tuple_new(book);
    EINA_ITERATOR_FOREACH(iter, t)
      _phonebook_entry_print(t->key, t->data);

reference/c/eina/src/eina_iterator.c

@@ -6,6 +6,15 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina Iterator examples.
+ *
+ * These examples demonstrate how to work with eina_iterator methods.
+ * Both an eina_list and an eina_array are created and an iterator obtained
+ * for both. You can see how we can use iterators irrespective of the source
+ * and also that there are different ways to work with iterating content.
+ */
+
 static Eina_Bool
 _print_item(const void *container EINA_UNUSED, void *data, void *fdata EINA_UNUSED)
 {

reference/c/eina/src/eina_list.c

@@ -6,11 +6,20 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina List examples.
+ *
+ * These examples demonstrate how to work with eina_list data and methods.
+ * We create a simple list of names by appending strings to an empty list
+ * and then run various mutations and print each result.
+ */
+
 static Eina_List *
 _list_create()
 {
    Eina_List *list = NULL;
 
+   // passing NULL as the list parameter will create a new list
    list = eina_list_append(list, "Adama");
    list = eina_list_append(list, "Baltar");
    list = eina_list_append(list, "Roslin");

reference/c/eina/src/eina_string.c

@@ -6,6 +6,17 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina String examples.
+ *
+ * These examples demonstrate how to work with eina_str, eina_strbuf and
+ * eina_stringshare. The eina_str_* methods are helper functions for managing
+ * strings, eina_stringshare provides methods for more easily managing the
+ * memory needed by strings, saving space and speeding up operations.
+ * Lastly eina_strbuf is an API for mutating strings optimally which can then
+ * provide stanard string exports to work with stanard string functions.
+ */
+
 static void
 _string_splitjoin()
 {
@@ -14,11 +25,13 @@ _string_splitjoin()
    char *joined;
    int i;
 
+   // split the string into an array on each occurrence of ";"
    printf("Name list split\n");
    arr = eina_str_split(names, ";", 0);
    for (i = 0; arr[i]; i++)
      printf(" %s\n", arr[i]);
 
+   // Here we re-join two of the strings with a different separator - "&"
    joined = malloc(sizeof(char) * 11);
    eina_str_join_len(joined, 11, '&', arr[0], strlen(arr[0]),
                      arr[1], strlen(arr[1]));
@@ -40,9 +53,10 @@ _string_case()
 
    eina_str_toupper(&str);
    printf(" Upper: %s\n", str);
+   free(str);
+
    eina_str_tolower(&str);
    printf(" Lower: %s\n", str);
-
    free(str);
 }
 
@@ -55,8 +69,11 @@ _string_startend()
    printf("File named %s:\n", file);
    printf(" starts with \"lib\"? %d\n", eina_str_has_prefix(file, "lib"));
    printf(" ends with \"efl.SO\"? %d\n", eina_str_has_suffix(file, "efl.SO"));
+
+   // The has_extension method is like has_suffix but case insensitive
    printf(" has extension \".SO\"? %d\n", eina_str_has_extension(file, ".SO"));
 
+   // we can also copy segments of a string
    start = malloc(sizeof(char) * 7);
    eina_strlcpy(start, file, 7);
    printf(" first 6 chars \"%s\"\n", start);
@@ -70,6 +87,8 @@ _string_escape()
    char *tmp;
 
    str = "Here's some \"example\" text.";
+
+   // backslash escaping a string for use on the command line, for example
    tmp = eina_str_escape(str);
    printf("String: %s\n", str);
    printf("Escaped: %s\n", tmp);
@@ -100,11 +119,14 @@ _string_share()
                        "%s will be revealed.";
    const char *line3 = "There are many copies. And they have a plan.";
 
+   // Creating a new stringshare which is deleted when we are done
+   // If other methods had referenced the string it would not delete immediately
    printf("Line1: %s\n", line1);
    str = eina_stringshare_add_length(line1, 31);
    printf(" limited to %d: %s\n", eina_stringshare_strlen(str), str);
    eina_stringshare_del(str);
 
+   // There are many helpful printf functions for formatting shared strings
    str = eina_stringshare_printf(line2, 12, 3, 4, "four");
    printf("Line2: %s\n", str);
    eina_stringshare_del(str);
@@ -112,6 +134,7 @@ _string_share()
    printf(" format limit (len %d): %s...\n", eina_stringshare_strlen(str), str);
    eina_stringshare_del(str);
 
+   // By replacing a stringshare it applies anywhere that references this share
    printf("Line3: %s\n", line3);
    str = eina_stringshare_add(line3);
    printf(" shared: %s\n", str);
@@ -125,12 +148,13 @@ _string_buf()
 {
    Eina_Strbuf *buf, *substr;
 
+   // populate a new bugger
    buf = eina_strbuf_new();
-
    eina_strbuf_append_length(buf, "BUFFE", 5);
    eina_strbuf_append_char(buf, 'R');
    printf("buffer: %s\n", eina_strbuf_string_get(buf));
 
+   // Demonstrating standard string functions using a strbuf
    eina_strbuf_tolower(buf);
    printf("lower: %s\n", eina_strbuf_string_get(buf));
 
@@ -143,6 +167,7 @@ _string_buf()
    eina_strbuf_reset(buf);
    printf("\n");
 
+   // we can even insert or remove content within the string buffer
    eina_strbuf_append_printf(buf, "%s%c", "buffe", 'r');
    eina_strbuf_insert_printf(buf, " %s: %d", 6, "length", (int)eina_strbuf_length_get(buf));
    printf("printf: %s\n", eina_strbuf_string_get(buf));

reference/c/eina/src/eina_value.c

@@ -6,6 +6,15 @@
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina Value examples.
+ *
+ * These examples demonstrate how to work with eina_value data and methods.
+ * Eina_Value is a way to represent and pass data of varying types and to
+ * convert efficiently between them..
+ * Eina_Value can even define structs for managing more complex requirements.
+ */
+
 static void
 _value_int()
 {
@@ -13,11 +22,13 @@ _value_int()
    char *str;
    int i;
 
+   // Setting up an integer value type
    eina_value_setup(&int_val, EINA_VALUE_TYPE_INT);
    eina_value_set(&int_val, 123);
    eina_value_get(&int_val, &i);
    printf("int_val value is %d\n", i);
 
+   // It can easily be converted it to a string
    str = eina_value_to_string(&int_val);
    printf("int_val to string is \"%s\"\n", str);
    free(str); // it was allocated by eina_value_to_string()
@@ -31,11 +42,14 @@ _value_string()
    const char *str;
    char *newstr;
 
+   // Setting up an integer value type
    eina_value_setup(&str_val, EINA_VALUE_TYPE_STRING);
    eina_value_set(&str_val, "My string");
    eina_value_get(&str_val, &str);
    printf("str_val value is \"%s\" (pointer: %p)\n", str, str);
 
+   // To string here will copy the data, so we still need to free it
+   // Notice that the pointer is different on the returned string
    newstr = eina_value_to_string(&str_val);
    printf("str_val to string is \"%s\" (pointer: %p)\n", newstr, newstr);
    free(newstr); // it was allocated by eina_value_to_string()
@@ -49,6 +63,7 @@ _value_convert()
    int i;
    char *str;
 
+   // set up string and int types to convert between
    eina_value_setup(&str_val, EINA_VALUE_TYPE_STRING);
    eina_value_setup(&int_val, EINA_VALUE_TYPE_INT);
 
@@ -86,6 +101,7 @@ _value_struct_define()
      EINA_VALUE_STRUCT_MEMBER(NULL, Struct, chr)
    };
 
+   // set up the members and describe the struct parameters
    members[0].type = EINA_VALUE_TYPE_INT;
    members[1].type = EINA_VALUE_TYPE_CHAR;
    static Eina_Value_Struct_Desc desc = {
@@ -121,6 +137,7 @@ _value_struct_print(Eina_Value *struct_val)
    printf("  num: %d\n", num);
    printf("  chr: %c\n", chr);
 
+   // we can check if a struct contains a field before working with it
    if (eina_value_struct_get(struct_val, "missing", &num))
      printf(  "missing: %d\n", num);
 }

reference/c/eina/src/eina_value_custom.c

@@ -2,10 +2,21 @@
 #define EFL_BETA_API_SUPPORT 1
 
 #include <stdio.h>
+#include <sys/time.h>
 
 #include <Eina.h>
 #include <Efl_Core.h>
 
+/*
+ * Eina Value custom examples.
+ *
+ * Eina_Value allows the definition of custom types which can be passed like
+ * any other Eina_Value. This example defines a custom timezone type and all
+ * the methods that must be implemented for a custom type.
+ * As this encapsulates the system timezone struct we initialise it from
+ * the gettimeofday method..
+ */
+
 static Eina_Bool
 _tz_setup(const Eina_Value_Type *type, void *mem)
 {