Update comments.

m-array.h

@@ -156,6 +156,7 @@
     type *ptr;              /* Pointer to the array base */             \
   } array_t[1];                                                         \
                                                                         \
+  /* Define an iterator over an array */                                \
   typedef struct M_C(name, _it_s) {                                     \
     size_t index;                       /* Index of the element */      \
     const struct M_C(name, _s) *array;  /* Reference of the array */    \

m-core.h

@@ -3169,9 +3169,12 @@ m_core_backoff_clear(m_core_backoff_ct backoff)
 /********************** Serialization ***********************/
 /************************************************************/
 
+/* Forward declaration of string_t defined in m-string.h */
+struct string_s;
+
 /* Serialization Return code:
- * - OK & done,
+ * - OK & done (object is fully parsed),
- * - OK & continue parsing (internal return code of the serialization)
+ * - OK & continue parsing (object is partially parsed)
  * - Fail parsing
  */
 typedef enum m_serial_return_code_e {
@@ -3217,29 +3220,28 @@ typedef union m_serial_ll_u {
 
 /* Object to handle the construction of a serial write/read of an object
    that needs multiple calls (array, map, ...)
-   It is common to all calls to the same object and is used a state of parsing 
+   It is common to all calls to the same object.
-   local to the current structure being parsed */
+   It shall be used as a local state of the object being parsed */
 typedef struct m_serial_local_s {
   m_serial_ll_ct data[M_SERIAL_MAX_DATA_SIZE];
 } m_serial_local_t[1];
 
 /* Object to handle the generic serial read of an object:
- *  - interface is the pointer to the constant interface object that has all callbacks
+ *  - m_interface is the pointer to the constant interface object that has all callbacks
- *  - tmp is temporary variable used localy by the non recursive serializer
+ *  - tmp is temporary variable used localy by the non recursive serializer (not to be used by serializer)
  *  - data is user defined data to use by the serialization object as it wants
- * NOTE: interface cannot be used as a field name as some system headers define it
+ * NOTE: 'interface' word cannot be used as a field name as some system headers
- * as a macro.
+ * define it as a macro.
  * */
 typedef struct m_serial_read_s {
   const struct m_serial_read_interface_s *m_interface;
-  m_serial_ll_ct                           tmp;
+  m_serial_ll_ct                          tmp;
-  m_serial_ll_ct                           data[M_SERIAL_MAX_DATA_SIZE];
+  m_serial_ll_ct                          data[M_SERIAL_MAX_DATA_SIZE];
 } m_serial_read_t[1];
 
-/* Forward declaration of string_t defined in m-string.h */
+/* Interface that has to be exported by the serial read object.
-struct string_s;
+ * All function pointers shall be not null.
-
+ */
-/* Interface that has to be exported by the serial read object. */
 typedef struct m_serial_read_interface_s {
   m_serial_return_code_t (*read_boolean)(m_serial_read_t,bool *);
   m_serial_return_code_t (*read_integer)(m_serial_read_t, long long *, const size_t size_of_type);
@@ -3258,17 +3260,21 @@ typedef struct m_serial_read_interface_s {
 
 
 /* Object to handle the generic serial write of an object:
- *  - interface is the pointer to the constant interface object that has all callbacks
+ *  - m_interface is the pointer to the constant interface object that has all callbacks
  *  - tmp is temporary variable used localy by the non recursive serializer
  *  - data is user defined data to use by the serialization object as it wants
+ * NOTE: 'interface' word cannot be used as a field name as some system headers
+ * define it as a macro.
  * */
 typedef struct m_serial_write_s {
   const struct m_serial_write_interface_s *m_interface;
   m_serial_ll_ct                           tmp;
-  m_serial_ll_ct                            data[M_SERIAL_MAX_DATA_SIZE];
+  m_serial_ll_ct                           data[M_SERIAL_MAX_DATA_SIZE];
 } m_serial_write_t[1];
 
-/* Interface that has to be exported by the serial write object. */
+/* Interface that has to be exported by the serial write object.
+ * All function pointers shall be not null.
+ */
 typedef struct m_serial_write_interface_s {
   m_serial_return_code_t (*write_boolean)(m_serial_write_t,const bool data);
   m_serial_return_code_t (*write_integer)(m_serial_write_t,const long long data, const size_t size_of_type);
@@ -3289,8 +3295,9 @@ typedef struct m_serial_write_interface_s {
 } m_serial_write_interface_t;
 
 
-/* Convert a C default variale (bool, integer, float) to a Serialized data.
+/* Convert a C default variale (bool, integer, float) to a Serialized data
-   Supports only C11.
+ * by calling the serializer interface associated to the type of the object.
+ * NOTE: Supports only C11.
 */
 #define M_OUT_SERIAL_DEFAULT_ARG(serial, x)                             \
   _Generic(((void)0,(x)),                                               \
@@ -3315,7 +3322,8 @@ typedef struct m_serial_write_interface_s {
            void *: M_SERIAL_FAIL /* unsupported */)
 
 /* Convert a Serialized data to a C default variale (bool, integer, float)
-   Supports only C11.
+ * by calling the serializer interface associated to the type of the object.
+ * NOTE: Supports only C11.
 */
 #define M_IN_SERIAL_DEFAULT_ARG(xptr, serial)                           \
   _Generic(((void)0,*(xptr)),                                           \
@@ -3372,6 +3380,7 @@ static inline long long
 m_core_in_serial_enum(m_serial_read_t serial)
 {
   long long i;
+  /* Store the return code temporary in the serialize object */
   serial->tmp.r = serial->m_interface->read_integer(serial, &i, sizeof (long long));
   return i;
 }
@@ -3388,6 +3397,8 @@ m_core_out_serial_strlen(const char s[])
 }
 
 /* Encapsulation of returning error,
+ * A serializer should return 'm_core_serial_fail()' instead of directly
+ * M_SERIAL_FAIL 
  * so that a breakpoint can be put on this function for debugging purpose.
  */
 static inline m_serial_return_code_t

m-list.h

@@ -162,14 +162,16 @@
  */
 #define LISTI_DEF_P3(name, type, oplist, list_t, it_t)                  \
                                                                         \
+  /* Define the node of a list, and the list as a pointer to a node */  \
   typedef struct M_C(name, _s) {                                        \
-    struct M_C(name, _s) *next;                                         \
+    struct M_C(name, _s) *next;  /* Next node or NULL if final node */  \
-    type data;                                                          \
+    type data;                   /* The data itself */                  \
   } *list_t[1];                                                         \
                                                                         \
+  /* Define an iterator of a list */                                    \
   typedef struct M_C(name, _it_s) {                                     \
-    struct M_C(name, _s) *previous;                                     \
+    struct M_C(name, _s) *previous; /* Previous node or NULL */         \
-    struct M_C(name, _s) *current;                                      \
+    struct M_C(name, _s) *current;  /* Current node or NULL */          \
   } it_t[1];                                                            \
                                                                         \
   /* Definition of the synonyms of the type */                          \
@@ -640,6 +642,8 @@
 
 /* Internal list function definition using only iterator functions 
    which is common for all kind of lists.
+   It shall therefore only used the public interface of a list
+   and no contract can be checked at this level.
    - name: prefix to be used
    - type: type of the elements of the list
    - oplist: oplist of the type of the elements of the container
@@ -859,6 +863,7 @@
  */
 #define LISTI_DUAL_PUSH_DEF_P3(name, type, oplist, list_t, it_t)        \
                                                                         \
+  /* Node of a list (it is liked the singly linked list) */             \
   struct M_C(name, _s) {                                                \
     struct M_C(name, _s) *next;                                         \
     type data;                                                          \
@@ -870,10 +875,11 @@
      This is done by keeping a pointer to both back & front             \
   */                                                                    \
   typedef struct M_C(name, _head_s)  {                                  \
-    struct M_C(name, _s) *front;                                        \
+    struct M_C(name,_s) *front; /* Pointer to the front node or NULL */ \
-    struct M_C(name, _s) *back;                                         \
+    struct M_C(name,_s) *back;  /* Pointer to the back node or NULL */  \
   } list_t[1];                                                          \
                                                                         \
+  /* Define the iterator over a dual push singly linked list */         \
   typedef struct M_C(name, _it_s) {                                     \
     struct M_C(name, _s) *previous;                                     \
     struct M_C(name, _s) *current;                                      \