From 15f58d5738e8bc96ca7ce5576af4afb642c1c6b7 Mon Sep 17 00:00:00 2001
From: Patrick Pelissier <patrick.pelissier@gmail.com>
Date: Sun, 23 Oct 2022 21:01:29 +0200
Subject: [PATCH] Update example comments.

---
 example/ex-array05.c       | 1 +
 example/ex-defer01.c       | 5 +++++
 example/ex-list01.c        | 5 +++--
 example/ex-multi05.c       | 9 ++++++++-
 example/ex-string03.c      | 3 ++-
 example/ex11-count-lines.c | 2 +-
 example/ex11-json01.c      | 2 ++
 7 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/example/ex-array05.c b/example/ex-array05.c
index 7e8f1abb..f257ed44 100644
--- a/example/ex-array05.c
+++ b/example/ex-array05.c
@@ -96,6 +96,7 @@ static void data_node_clear(data_node *obj)
    and gives the minimum oplist allowing M*LIB to handle
    properly the object 'data_node' with the API convention
    to respect for calling the methods.
+   The Manual defines the different supported API.
 */
 ARRAY_DEF(/* the array prefix */ array_data_node,
 	  /* the object type */ data_node,
diff --git a/example/ex-defer01.c b/example/ex-defer01.c
index dd85d91f..ac508e8e 100644
--- a/example/ex-defer01.c
+++ b/example/ex-defer01.c
@@ -1,5 +1,10 @@
 #include "m-core.h"
 
+/* This example show how to use the M_LET_IF macro
+   that enables to construct an object and continue
+   if the construction succeeds.
+*/
+
 // Stubs defined for the example. Real code will use soundio library.
 struct SoundIo { int x; };
 struct SoundIoDevice { int x; };
diff --git a/example/ex-list01.c b/example/ex-list01.c
index 71af822b..b050f9b4 100644
--- a/example/ex-list01.c
+++ b/example/ex-list01.c
@@ -28,11 +28,11 @@ int main(void)
   M_LET (grow, list_string_t)
     M_LET (tmpstr, string_t) { // And let's create also a string_t
 
-    // add string elements to the list
+    // add string elements to the list in different ways
     list_string_push_back (grow, STRING_CTE("AB"));
     string_printf(tmpstr, "%d", 12);
     list_string_push_back (grow, tmpstr);
-    list_string_push_back (grow, STRING_CTE("CD"));
+    list_string_emplace_back (grow, "CD");
 
     // Serialize the list of string into a big string.
     list_string_get_str (tmpstr, grow, false);
@@ -75,6 +75,7 @@ int main(void)
     // Split a string into a list.
     string_set_str(tmpstr, "HELLO;JOHN;HOW;ARE;YOU");
     astring_split(grow, tmpstr, ';');
+    // Iterate over the splitted list
     for M_EACH (item, grow, list_string_t) {
         printf ("Split Item = %s\n", string_get_cstr(*item) );
       }
diff --git a/example/ex-multi05.c b/example/ex-multi05.c
index da78e802..497ae53e 100644
--- a/example/ex-multi05.c
+++ b/example/ex-multi05.c
@@ -3,7 +3,14 @@
 #include "m-array.h"
 #include "m-string.h"
 
-// Let's create an array of string_t and register it globaly
+/* This example show ARRAY_DEF usage with string,
+   M_LET macro usage with complex initialization condition:
+   how to initialize a dynamic array and initialize it with the given arguments.
+   It show also the M_EACH keywork
+*/
+
+// Let's create a dynamic array of string_t and register it globaly
+// a so called std::vector<std::string> in C++
 ARRAY_DEF(vector_string, string_t)
 #define M_OPL_vector_string_t() ARRAY_OPLIST(vector_string, STRING_OPLIST)
 
diff --git a/example/ex-string03.c b/example/ex-string03.c
index b3410720..4464db6c 100644
--- a/example/ex-string03.c
+++ b/example/ex-string03.c
@@ -26,13 +26,14 @@ int main(void)
 
         // Count the words.
         M_LET(map, dict_str_t) {
-            // Count the words:
+            // Count the words into the dictionnary 'map'
             for M_EACH(w, words, vector_str_t) {
                 (*dict_str_safe_get(map, *w)) ++;
             }
 
             // Print the count:
             for M_EACH(p, map, dict_str_t) {
+                // In C11 version we can use the M_PRINT macro that simplifies formatting.
 #if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L)            
                 M_PRINT(p->value, " occurences of ", p->key, "\n");
 #else
diff --git a/example/ex11-count-lines.c b/example/ex11-count-lines.c
index df24671f..cd03af06 100644
--- a/example/ex11-count-lines.c
+++ b/example/ex11-count-lines.c
@@ -38,7 +38,7 @@ M_TREE_DEF(tree, dir_t)
 static tree_it_t
 add_directory(tree_it_t parent, const string_t dirname)
 {
-  // Miss: return dir_emplace_child(parent, 0, dirname); to simplify this function.
+  // TODO: return dir_emplace_child(parent, 0, dirname); to simplify this function.
   // which is too complex for what she does.
   dir_t data;
   tree_it_t it;
diff --git a/example/ex11-json01.c b/example/ex11-json01.c
index 3f6eae67..746d73e8 100644
--- a/example/ex11-json01.c
+++ b/example/ex11-json01.c
@@ -2,6 +2,8 @@
 #include "m-tuple.h"
 #include "m-array.h"
 
+/* Basic example to show JSON serialization */
+
 // Let's define a 'person' composed of several fields.
 TUPLE_DEF2(person,
            (surname, string_t),