From ec4c12eab57f9ef6838f6b37e90356bf05f8f77b Mon Sep 17 00:00:00 2001
From: Patrick Pelissier <patrick.pelissier@gmail.com>
Date: Sat, 8 Jul 2017 12:57:28 +0200
Subject: [PATCH] Update comments.

---
 example/ex-multi03.c | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/example/ex-multi03.c b/example/ex-multi03.c
index 1c06a36d..7957de55 100644
--- a/example/ex-multi03.c
+++ b/example/ex-multi03.c
@@ -1,8 +1,8 @@
 #include <time.h>
 #include <stdio.h>
 
-/* Register a dynamic seed to M*LIB. 
-   Shall be done before any M*LIB header inclusion. */
+/* Register a dynamic seed to M*LIB hash function. 
+   This shall be done before any M*LIB header inclusion. */
 unsigned long long rand_seed;
 #define M_HASH_SEED rand_seed
 
@@ -14,11 +14,12 @@ unsigned long long rand_seed;
 /* This example will show how to create JSON-like files.
    This is a JSON **like** syntax, not exactly JSON format */
 
-/* OUT/IN of boolean */
+/* First let's handle the OUT/IN functions of boolean */
 static inline void boolean_out_str(FILE *f, bool b)
 {
   fprintf(f, b ? "TRUE" : "FALSE");
 }
+
 static inline bool boolean_in_str(bool *b, FILE *f)
 {
   char c = fgetc(f);
@@ -45,17 +46,19 @@ static inline bool boolean_in_str(bool *b, FILE *f)
   }
 }
 
-/* OUT/IN of float */
+/* Then the OUT/IN functions of float */
 static inline void real_out_str(FILE *f, float r)
 {
   fprintf(f, "%f", r);
 }
+
 static inline bool real_in_str(float *r, FILE *f)
 {
   return fscanf(f, "%f", r) == 1;
 }
 
-/* Header definition */
+
+/* Let's define the header & its interface */
 
 typedef struct json_node_s *json_t;
 
@@ -68,9 +71,10 @@ extern void json_set (json_t *, json_t);
 extern void json_out_str(FILE *, json_t);
 extern bool json_in_str(json_t *, FILE *);
 
-#define JSON_OPLIST (INIT(json_init M_IPTR), CLEAR(json_clear),         \
-                     INIT_SET(json_init_set M_IPTR), SET(json_set M_IPTR),\
-                     OUT_STR(json_out_str), IN_STR(json_in_str M_IPTR) )
+#define JSON_OPLIST                                                     \
+  (INIT(json_init M_IPTR), CLEAR(json_clear),                           \
+   INIT_SET(json_init_set M_IPTR), SET(json_set M_IPTR),                \
+   OUT_STR(json_out_str), IN_STR(json_in_str M_IPTR) )
 
 DICT_DEF2(json, string_t, STRING_OPLIST, json_t, JSON_OPLIST)
 
@@ -155,14 +159,15 @@ static json_t generate(void)
   array_json_t a;
   string_t s;
 
-  /* This is low level generation as it is an example */
+  /* This is a low level generation for example */
   json_init_new(&p);
   json_init_new(&k);
   array_json_init(a);
   dict_json_init(d);
   string_init (s);
 
-  /* { channel: TRUE, filter: 2.3, tab: [2., 3.] } */
+  /* Let's generate the following structure :
+     { channel: TRUE, filter: 2.3, tab: [2., 3.] } */
   variant_json_set_boolean(k->json, true);
   dict_json_set_at(d, STRING_CTE("channel"), k);
   variant_json_set_real(k->json, 2.3);
@@ -194,7 +199,8 @@ int main(void)
   json_out_str(stdout, p);
   /* Typical Output:
     @dict@{"filter":@real@2.300000@,"tab":@array@[@real@2.000000@,@real@3.000000@]@,"channel":@boolean@TRUE@}@
-  */
+    If you want a true JSON format, you'll have to overload the variant IN/OUT function so that they
+    can detect the type of argument and, as such, don't need to output it in the format */
   printf("\n");
   json_clear(p);
   return 0;