From 1380a91bf1971fe04cb3f5643227eb2e5a6a6eaa Mon Sep 17 00:00:00 2001
From: Patrick Pelissier <patrick.pelissier@gmail.com>
Date: Mon, 17 Sep 2018 22:20:39 +0200
Subject: [PATCH] Update comments.

---
 m-core.h | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/m-core.h b/m-core.h
index e54f83a2..5e0a297e 100644
--- a/m-core.h
+++ b/m-core.h
@@ -679,7 +679,8 @@
 #define M_IFI_1(true_macro, ...)    true_macro
 #define M_IF(c)                     M_C(M_IFI_, M_BOOL(c))
 
-/* Return 1 if there is a comma inside the argument list, 0 otherwise */
+/* Return 1 if there is a comma inside the argument list,
+   0 otherwise. */
 #define M_COMMA_P(...)              M_RET_ARG53(__VA_ARGS__, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, useless)
 
 /* Return the string representation of the evaluated x.
@@ -705,9 +706,9 @@
 #define M_PARENTHESISI_DETECT(...)  0, 1,
 #define M_PARENTHESIS_P(...)        M_AND(M_COMMA_P(M_PARENTHESISI_DETECT __VA_ARGS__), M_INV(M_COMMA_P(__VA_ARGS__)))
 
-/* Necessary macros to handle recursivity */
-/* Delay the evaluation by one level or two or three or ... */
-/* The argument is a macro-function which has to be deferred */
+/* Necessary macros to handle recursivity,
+   delaying the evaluation by one (or more) level of macro expansion.
+   The argument is a macro-function which has to be deferred */
 #define M_DELAY0()
 #define M_DELAY1(...)               __VA_ARGS__ M_DELAY0 ()
 #define M_DELAY2(...)               __VA_ARGS__ M_DELAY1 (M_DELAY0) ()
@@ -719,10 +720,11 @@
 #define M_DELAY8(...)               __VA_ARGS__ M_DELAY7 (M_DELAY0) ()
 #define M_DELAY9(...)               __VA_ARGS__ M_DELAY8 (M_DELAY0) ()
 
-/* Perform 3^5 evaluation 
- NOTE: There can be only one eval per complete macro-evaluation pass.
- If there is multiple macro using recursivity, only one M_EVAL
- can exist.*/
+/* Perform 3^5 evaluation,
+   forcing the pre-processor to expand the given macro a lot of times. 
+   NOTE: There can be only one EVAL macro per complete macro-evaluation pass.
+   As such the given macro cannot contain M_EVAL itself.
+*/
 #define M_EVAL(...)                 M_EVAL1(M_EVAL1(M_EVAL1(__VA_ARGS__)))
 #define M_EVAL1(...)                M_EVAL2(M_EVAL2(M_EVAL2(__VA_ARGS__)))
 #define M_EVAL2(...)                M_EVAL3(M_EVAL3(M_EVAL3(__VA_ARGS__)))
@@ -734,8 +736,10 @@
    It allows that a won't be evaluated until all arguments of 'a' have been already evaluated */
 #define M_APPLY(a, ...) a (__VA_ARGS__)
 
-/* Map: apply the given macro to all arguments (non recursive version) */
-/* Example: M_MAP(f,a, b, c) ==> f(a) f(b) f(c) */
+/* MAP: apply the given macro to all arguments.
+   It is a non recursive version that is much faster than the recursive one.
+   Example: 
+   M_MAP(f,a, b, c) ==> f(a) f(b) f(c) */
 /* Generated by:
    for i in $(seq 1 52) ; do printf "#define M_MAP_%d(f" $i ; for j in $(seq 1 $i) ; do printf ", _%d" $j ; done ; printf ") " ; for j in $(seq 1 $i) ; do printf "f(_%d) " $j ; done ; printf "\n"; done
 */