tidy up the reference macro, rename dereference function; [examples] tidy up the commentary about for loop macros

examples/metaprograms/datadesk_like_template.c

@@ -73,7 +73,7 @@ int main(int argument_count, char **arguments)
         Initialize();
         for(MD_EachNode(ref, list->first_child))
         {
-            MD_Node *root = MD_NodeFromReference(ref);
+            MD_Node *root = MD_ResolveNodeFromReference(ref);
             for(MD_EachNode(node, root->first_child))
             {
                 TopLevel(node);

examples/metaprograms/node_errors.c

@@ -22,7 +22,7 @@ int main(int argument_count, char **arguments)
     // NOTE(rjf): Print errors on every single node.
     for(MD_EachNode(ref, list->first_child))
     {
-        MD_Node *root = MD_NodeFromReference(ref);
+        MD_Node *root = MD_ResolveNodeFromReference(ref);
         for(MD_EachNode(node, root->first_child))
         {
             MD_PrintNodeMessageFmt(stderr, node, MD_MessageKind_Error, "This node has an error!");

examples/metaprograms/parse_check.c

@@ -73,20 +73,23 @@ int main(int argument_count, char **arguments)
     }
     
     // print the verbose parse results
-    // @notes The Metadesk library provides a few macros for iterating MD_Node
-    //  lists as shown here. The first parameter to the macro becomes an
-    //  MD_Node pointer in the scope of the for loop that visits each node in
-    //  the list in order. The second parameter is a pointer to the first node
-    //  in the list. Generally we past the `first_child` of a list or parent
-    //  MD_Node, but we don't always have to.
-    //
-    //  MD_EachNode is used to iterate a list of children.
-    //  MD_EachNodeRef is used to iterate a list of references like the list
-    //   of roots from the parses we have built. Underneath the surface this
-    //   macro automatically resolves the reference at the beginning of each
-    //   loop step.
-    for (MD_EachNodeRef(root, list->first_child))
+    // @notes The Metadesk library provides a macros for iterating chains of
+    //  MD_Node as shown here. The first parameter to the macro names an
+    //  MD_Node pointer in the for loop that iterates through each node in the
+    //  list. The second parameter is a pointer to the first node of the list.
+    //  Generally we past the `first_child` of a list or parent MD_Node, but we
+    // don't always have to.
+    for (MD_EachNode(root_it, list->first_child))
     {
+        
+        // @notes The `list` we have been building does not contain a normal
+        //  MD_Node chain like in the trees returned from the parser. Instead
+        //  it contains a chain of 'reference' nodes, which can point to any
+        //  metadesk node from a previous parse. So our `root_it` is iterating
+        //  a list of reference nodes. Here we resolve the reference node to
+        //  get the root of the parse tree.
+        MD_Node *root = MD_ResolveNodeFromReference(root_it);
+        
         for (MD_EachNode(node, root->first_child))
         {
             // @notes The Metadesk library likes to use MD_String8List for

source/md.c

@@ -2837,7 +2837,7 @@ MD_TagCountFromNode(MD_Node *node)
 }
 
 MD_FUNCTION_IMPL MD_Node *
-MD_NodeFromReference(MD_Node *node)
+MD_ResolveNodeFromReference(MD_Node *node)
 {
     MD_u64 safety = 100;
     for(; safety > 0 && node->kind == MD_NodeKind_Reference;

source/md.h

@@ -1087,17 +1087,13 @@ MD_FUNCTION MD_Node *  MD_TagArgFromString(MD_Node *node, MD_String8 tag_string,
 MD_FUNCTION MD_b32     MD_NodeHasTag(MD_Node *node, MD_String8 tag_string, MD_MatchFlags flags);
 MD_FUNCTION MD_i64     MD_ChildCountFromNode(MD_Node *node);
 MD_FUNCTION MD_i64     MD_TagCountFromNode(MD_Node *node);
-MD_FUNCTION MD_Node *  MD_NodeFromReference(MD_Node *node);
+MD_FUNCTION MD_Node *  MD_ResolveNodeFromReference(MD_Node *node);
 
 MD_FUNCTION MD_String8 MD_PrevCommentFromNode(MD_Node *node);
 MD_FUNCTION MD_String8 MD_NextCommentFromNode(MD_Node *node);
 
 // NOTE(rjf): For-Loop Helpers
 #define MD_EachNode(it, first) MD_Node *it = (first); !MD_NodeIsNil(it); it = it->next
-#define MD_EachNodeRef(it, first) \
-MD_Node *it##_r = (first), *it = MD_NodeFromReference(it##_r); \
-!MD_NodeIsNil(it##_r); \
-it##_r = it##_r->next, it = MD_NodeFromReference(it##_r)
 
 //~ Error/Warning Helpers
 

tests/expression_tests.c

@@ -336,7 +336,7 @@ int main(void){
                     for(MD_Message *message = expr_parse.errors.first; message; message = message->next){
                         if(message->node->offset != test.error_offset){
                             printf("Example %d : \"%.*s\". Expected error on character %d; got character %ld instead\n", 
-                                   i_test, MD_S8VArg(q), test.error_offset, message->node->offset);
+                                   i_test, MD_S8VArg(q), test.error_offset, (long)message->node->offset);
                         }
                     }
                 }
@@ -352,7 +352,7 @@ int main(void){
                 for(MD_Message *message = parse.errors.first; message; message = message->next){
                     if(message->node->offset != test.error_offset){
                         printf("Example %d : \"%.*s\". Expected error on character %d; got character %ld instead\n", 
-                               i_test, MD_S8VArg(q), test.error_offset, message->node->offset);
+                               i_test, MD_S8VArg(q), test.error_offset, (long)message->node->offset);
                     }
                 }
             }