Add some comments to better explain the source.

example/ex-array01.c

@@ -1,16 +1,35 @@
+/*
+ * All the definition are included in the file m-array.h
+ * You don't need to link with any library.
+ */
 #include "m-array.h"
 
-// Let's define an array of 'char *' named 'charp'
+// First you need to instanciate your code for the type you want.
+// This is done by calling the ARRAY_DEF macro with the name
+// of the instance (here array_charp) and the type of the instance
+// (here a pointer to char).
+// This will create all types and functions to handle an
+// array of char pointers.
+// So let's define an array of 'char *' named 'array_charp'
 ARRAY_DEF (array_charp, char *)
+// Ok everything has been defined. We can use everything like
+// standard C function.
 
 int main(void)
 {
-  // Create an array list
+  // Declare an array of 'char *'.
+  // The used name for the container is the name concatened with '_t'.
   array_charp_t al;
-  // Initialize it
+
+  // Like a good POD it needs to be explicitly initialized.
+  // Notice that we don't to pass the address of the variable as input
+  // to the function, but the variable.
+  // In fact, the array is automatically passed by reference to any
+  // function.
   array_charp_init(al);
       
-  // add elements to the array list
+  // Let's do some basic stuff:
+  // add some elements to the array list
   array_charp_push_back (al,"C");
   array_charp_push_back (al,"A");
   array_charp_push_back (al,"E");
@@ -20,14 +39,29 @@ int main(void)
 
   // Use iterator to display contents of al
   printf("Original contents of al: ");
+  // The iterator has also been defined with the ARRAY_DEF macro.
+  // All iterators of all containers follow the same logic,
+  // so that you can change the type of the container without
+  // changing your code.
   array_charp_it_t itr;
+  // You initialized the iterator to the first element of the container,
+  // iterate until not the end of the container is reached,
+  // while moving the iterator to the next element of the array.
+  // This is pretty overkill for an array, but this works for any container.
   for (array_charp_it(itr, al) ; !array_charp_end_p (itr); array_charp_next(itr)) {
+    // Let's get a reference to the data pointed by the iterator.
+    // You'll always get a pointer to this data, not the data itself.
+    // So you need an extra '*' to read the data.
     char *element = *array_charp_ref(itr);
     printf ("%s ", element);
   }
   printf("\n");
       
   // Now, display the list backwards
+  // As the iterator as reached the end of the array,
+  // let's go back by one element,
+  // iterate until not the end of the container is reached,
+  // while moving the iterator to the previous element of the array.
   printf("Array backwards: ");
   for (array_charp_previous (itr) ; !array_charp_end_p (itr); array_charp_previous(itr)) {
     char *element = *array_charp_ref(itr);
@@ -35,15 +69,19 @@ int main(void)
   }
   printf("\n");
 
-  // For array, we can also iterate over the integer
+  // As it is an array, we can also iterate using a standard integer:
   printf("Array Direct: ");
   for(size_t i = 0 ; i < array_charp_size(al); ++i) {
+    // Like for getting a reference of an iterator
+    // the get operator returns a pointer to the data.
+    // This allows handling non-copying type within the container
+    // (like array).
     char *element = *array_charp_get(al, i);
     printf ("%s ", element);
   }
   printf("\n");
 
-  // Clear the array
+  // Like POD, we need to clear the array explicitly
   array_charp_clear(al);
   return 0;
 }

example/ex-array02.c

@@ -1,14 +1,31 @@
+// This is the same example as ex-array01.c
+// It uses some macros to simplify the writing of the code.
+// So it is a shorter version of the first example.
 #include "m-array.h"
 
-// Let's define an array of 'char *' named 'charp'
+// Let's define an array of 'char *' named 'array_charp'
 ARRAY_DEF (array_charp, char *)
-// Let's register globaly the oplist of array_charp
-#define M_OPL_array_charp_t() ARRAY_OPLIST(array_charp)
 
+// Let's register globaly the oplist of array_charp
+// This is done by defining a macro named M_OPL_ and the type
+// of the containern, like this:
+#define M_OPL_array_charp_t() ARRAY_OPLIST(array_charp)
+// An oplist is the interface published by the type.
+// It contains all exported methods of the type
+// (and which functions shall be called to handle them).
+// It is both an input of the ARRAY_DEF macro (the last argument)
+// if the type used to create the container has non-standard
+// requirements (like pretty much any C structure) and an output
+// (using ARRAY_OPLIST) which provides the updated oplist
+// which will handle the container itself.
 
 int main(void)
 {
-  // Create an array list 'al' of type array_charp_t
+  // Create an array list 'al' of type 'array_charp_t'
+  // M_LET will check if a global oplist has been registered
+  // with the name array_charp_t, and if it finds it, will
+  // define the type, initializes it and clears it after
+  // it disappears from the bracket:
   M_LET (al, array_charp_t) {
     // add elements to the array list
     array_charp_push_back (al,"C");
@@ -20,7 +37,16 @@ int main(void)
 
     // Display contents of al
     printf("Original contents of al: ");
-    // For each element of the array al
+    // M_EACH is a macro which iterates over a container.
+    // It first argument is the name of the created variable
+    // which will be a pointer to one element of the container,
+    // al is the container to iterate,
+    // the last argument is either the type of the container
+    // (if a global oplist has been registered) or is the oplist
+    // of the container (if none).
+    // Indeed the macro needs to access the methods of the container
+    // to iterate over the container.
+    // So for each element of the array al
     for M_EACH(element, al, array_charp_t) {
         printf ("%s ", *element);
     }