some words explaining struct inst a little

1 files changed, 22 insertions, 8 deletions

diff --git a/compile.c b/compile.c
index eb0fe78d..3a094721 100644
--- a/compile.c
+++ b/compile.c
@@ -6,6 +6,18 @@
 #include "bytecode.h"
 #include "locfile.h"
 
+/*
+  The intermediate representation for jq filters is as a sequence of
+  struct inst, which form a doubly-linked list via the next and prev
+  pointers. 
+
+  A "block" represents a sequence of "struct inst", which may be
+  empty.
+
+  Blocks are generated by the parser bottom-up, so may have free
+  variables (refer to things not defined). See inst.bound_by and
+  inst.symbol.
+ */
 struct inst {
   struct inst* next;
   struct inst* prev;
@@ -22,18 +34,20 @@ struct inst {
   location source;
 
   // Binding
-  // An instruction requiring binding (for parameters/variables)
+  // An instruction requiring binding (for parameters/variables/functions)
   // is in one of three states:
-  //   bound_by = NULL  - Unbound free variable
-  //   bound_by = self  - This instruction binds a variable
-  //   bound_by = other - Uses variable bound by other instruction
-  // The immediate field is generally not meaningful until instructions
-  // are bound, and even then only for instructions which bind.
+  //   inst->bound_by = NULL  - Unbound free variable
+  //   inst->bound_by = inst  - This instruction binds a variable
+  //   inst->bound_by = other - Uses variable bound by other instruction
+  // Unbound instructions (references to other things that may or may not 
+  // exist) are created by "gen_foo_unbound", and bindings are created by
+  // block_bind(definition, body), which binds all instructions in
+  // body which are unboudn and refer to "definition" by name.
   struct inst* bound_by;
   char* symbol;
 
-  block subfn;
-  block arglist;
+  block subfn;   // used by CLOSURE_CREATE (body of function)
+  block arglist; // used by CLOSURE_CREATE (formals) and CALL_JQ (arguments)
 
   // This instruction is compiled as part of which function?
   // (only used during block_compile)