8 files changed, 43 insertions, 15 deletions
diff --git a/src/asm2wasm.h b/src/asm2wasm.h
index e68a06dc6..1c1f2e7cc 100644
--- a/src/asm2wasm.h
+++ b/src/asm2wasm.h
@@ -12,7 +12,7 @@ namespace wasm {
 
 using namespace cashew;
 
-int debug = 0;
+int debug = 0; // wasm::debug is set in main(), typically from an env var
 
 // Utilities
 
diff --git a/src/mixed_arena.h b/src/mixed_arena.h
index a92026580..dfd9bcb09 100644
--- a/src/mixed_arena.h
+++ b/src/mixed_arena.h
@@ -1,7 +1,10 @@
 
 #include <vector>
 
+//
 // Arena allocation for mixed-type data.
+//
+
 struct MixedArena {
   std::vector<char*> chunks;
   int index; // in last chunk
diff --git a/src/pretty_printing.h b/src/pretty_printing.h
index 71a729625..cc2d88272 100644
--- a/src/pretty_printing.h
+++ b/src/pretty_printing.h
@@ -1,4 +1,8 @@
 
+//
+// Pretty printing helpers
+//
+
 #include <ostream>
 
 #include "colors.h"
diff --git a/src/wasm-interpreter.h b/src/wasm-interpreter.h
index 8aeab2e97..dc88e296a 100644
--- a/src/wasm-interpreter.h
+++ b/src/wasm-interpreter.h
@@ -1,7 +1,8 @@
 
 //
-// Simple WebAssembly interpreter, designed to be embeddable in JavaScript, so it
-// can function as a polyfill.
+// Simple WebAssembly interpreter. This operates directly on the AST,
+// for simplicity and clarity. A goal is for it to be possible for
+// people to read this code and understand WebAssembly semantics.
 //
 
 #include <limits.h>
@@ -32,7 +33,13 @@ enum {
 };
 
 //
-// An instance of a WebAssembly module, which can execute it via AST interpretation
+// An instance of a WebAssembly module, which can execute it via AST interpretation.
+//
+// To embed this interpreter, you need to provide an ExternalInterface instance
+// (see below) which provides the embedding-specific details, that is, how to
+// connect to the embedding implementation.
+//
+// To call into the interpreter, use callExport.
 //
 
 class ModuleInstance {
diff --git a/src/wasm-js.cpp b/src/wasm-js.cpp
index a65eedd0f..c522a71f6 100644
--- a/src/wasm-js.cpp
+++ b/src/wasm-js.cpp
@@ -1,3 +1,4 @@
+
 //
 // WebAssembly intepreter for asm2wasm output, in a js environment.
 //
@@ -44,27 +45,33 @@ extern "C" void EMSCRIPTEN_KEEPALIVE load_asm(char *input) {
     end--;
   }
 
-  int debug = 0;
-
-  if (debug) std::cerr << "parsing...\n";
+#if WASM_JS_DEBUG
+  std::cerr << "parsing...\n";
+#endif
   cashew::Parser<Ref, DotZeroValueBuilder> builder;
   Ref asmjs = builder.parseToplevel(input);
 
   module = new Module();
   module->memory.initial = module->memory.max = 16*1024*1024; // TODO: receive this from emscripten
 
-  if (debug) std::cerr << "wasming...\n";
+#if WASM_JS_DEBUG
+  std::cerr << "wasming...\n";
+#endif
   asm2wasm = new Asm2WasmBuilder(*module);
   asm2wasm->processAsm(asmjs);
 
-  if (debug) std::cerr << "optimizing...\n";
+#if WASM_JS_DEBUG
+  std::cerr << "optimizing...\n";
+#endif
   asm2wasm->optimize();
 
 #if WASM_JS_DEBUG
   std::cerr << *module << '\n';
 #endif
 
-  if (debug) std::cerr << "generating exports...\n";
+#if WASM_JS_DEBUG
+  std::cerr << "generating exports...\n";
+#endif
   EM_ASM({
     Module['asmExports'] = {};
   });
@@ -78,7 +85,9 @@ extern "C" void EMSCRIPTEN_KEEPALIVE load_asm(char *input) {
     }, curr->name.str);
   }
 
-  if (debug) std::cerr << "creating instance...\n";
+#if WASM_JS_DEBUG
+  std::cerr << "creating instance...\n";
+#endif
 
   struct JSExternalInterface : ModuleInstance::ExternalInterface {
     Literal callImport(Import *import, ModuleInstance::LiteralList& arguments) override {
diff --git a/src/wasm-s-parser.h b/src/wasm-s-parser.h
index 642a28606..eb86376ab 100644
--- a/src/wasm-s-parser.h
+++ b/src/wasm-s-parser.h
@@ -1,6 +1,7 @@
 
 //
-// Parses WebAssembly code in S-Expression format, as in .wast files.
+// Parses WebAssembly code in S-Expression format, as in .wast files
+// such as are in the spec test suite.
 //
 
 #include <cmath>
@@ -11,7 +12,7 @@
 
 namespace wasm {
 
-int debug;
+int debug = 0; // wasm::debug is set in main(), typically from an env var
 
 using namespace cashew;
 
diff --git a/src/wasm-shell.cpp b/src/wasm-shell.cpp
index 26ce56e8e..6b7586719 100644
--- a/src/wasm-shell.cpp
+++ b/src/wasm-shell.cpp
@@ -1,6 +1,8 @@
 
 //
-// A WebAssembly shell, loads a .wast file (WebAssembly in S-Expression format) and executes it.
+// A WebAssembly shell, loads a .wast file (WebAssembly in S-Expression format)
+// and executes it. This provides similar functionality as the reference
+// interpreter, like assert_* calls, so it can run the spec test suite.
 //
 
 #include <setjmp.h>
diff --git a/src/wasm.h b/src/wasm.h
index c292e6bc6..16685d596 100644
--- a/src/wasm.h
+++ b/src/wasm.h
@@ -1,5 +1,7 @@
+
 //
-// wasm.js: WebAssembly representation and processing library
+// wasm.h: WebAssembly representation and processing library, in one
+//         header file.
 //
 // This represents WebAssembly in an AST format, with a focus on making
 // it easy to not just inspect but also to process. For example, some