chore: rename source files to wren_ prefix and add module-level documentation headers

src/compiler.h

@@ -1,8 +0,0 @@
-#ifndef wren_parser_h
-#define wren_parser_h
-
-#include "vm.h"
-
-ObjFn* wrenCompile(WrenVM* vm, const char* source);
-
-#endif

src/wren_common.h

@@ -1,6 +1,13 @@
 #ifndef wren_common_h
 #define wren_common_h
 
+// This header contains macros and defines used across the entire Wren
+// implementation. In particular, it contains "configuration" defines that
+// control how Wren works. Some of these are only used while hacking on
+// debugging Wren itself.
+//
+// This header is *not* intended to be included by code outside of Wren itself.
+
 // Define this to stress test the GC. It will perform a collection before every
 // allocation.
 //#define DEBUG_GC_STRESS

src/wren_compiler.c

@@ -3,10 +3,15 @@
 #include <stdarg.h>
 #include <string.h>
 
-#include "common.h"
-#include "compiler.h"
+#include "wren_common.h"
+#include "wren_compiler.h"
 
-#define MAX_NAME 256
+// This is written in bottom-up order, so the tokenization comes first, then
+// parsing/code generation. This minimizes the number of explicit forward
+// declarations needed.
+
+// The maximum length of a method signature.
+#define MAX_METHOD_NAME 256
 
 // TODO(bob): Are these really worth the effort?
 #define PUSH_SCOPE  \
@@ -1006,7 +1011,7 @@ static void this_(Compiler* compiler, int allowAssignment)
 // Subscript or "array indexing" operator like `foo[bar]`.
 static void subscript(Compiler* compiler, int allowAssignment)
 {
-  char name[MAX_NAME];
+  char name[MAX_METHOD_NAME];
   int length = 1;
   int numArgs = 0;
 
@@ -1041,7 +1046,7 @@ static void subscript(Compiler* compiler, int allowAssignment)
 
 void call(Compiler* compiler, int allowAssignment)
 {
-  char name[MAX_NAME];
+  char name[MAX_METHOD_NAME];
   int length = 0;
   int numArgs = 0;
 
@@ -1376,7 +1381,7 @@ void method(Compiler* compiler, Code instruction, SignatureFn signature)
   int constant = initCompiler(&methodCompiler, compiler->parser, compiler, 1);
 
   // Build the method name.
-  char name[MAX_NAME];
+  char name[MAX_METHOD_NAME];
   int length = compiler->parser->previous.end -
                compiler->parser->previous.start;
   strncpy(name, compiler->parser->source + compiler->parser->previous.start,

src/wren_compiler.h

@@ -0,0 +1,26 @@
+#ifndef wren_parser_h
+#define wren_parser_h
+
+#include "wren_vm.h"
+
+// This module defines the compiler for Wren. It takes a string of source code
+// and lexes, parses, and compiles it. Wren uses a single-pass compiler. It
+// does not build an actual AST during parsing and then consume that to
+// generate code. Instead, the parser directly emits bytecode.
+//
+// This forces a few restrictions on the grammar and semantics of the language.
+// Things like forward references and arbitrary lookahead are much harder. We
+// get a lot in return for that, though.
+//
+// The implementation is much simpler since we don't need to define a bunch of
+// AST data structures. More so, we don't have to deal with managing memory for
+// AST objects. The compiler does almost no dynamic allocation while running.
+//
+// Compilation is also faster since we don't create a bunch of temporary data
+// structures and destroy.
+
+// Compiles [source], a string of Wren source code, to an [ObjFn] that will
+// execute that code when invoked.
+ObjFn* wrenCompile(WrenVM* vm, const char* source);
+
+#endif

src/wren_core.c

@@ -5,7 +5,7 @@
 #include <time.h>
 
 #include "wren_core.h"
-#include "value.h"
+#include "wren_value.h"
 
 // Binds a native method named [name] (in Wren) implemented using C function
 // [fn] to `ObjClass` [cls].

src/wren_core.h

@@ -1,7 +1,7 @@
 #ifndef wren_core_h
 #define wren_core_h
 
-#include "vm.h"
+#include "wren_vm.h"
 
 // This module defines the built-in classes and their native methods that are
 // implemented directly in C code. Some languages try to implement as much of

src/wren_value.c

@@ -1,8 +1,8 @@
 #include <stdio.h>
 #include <string.h>
 
-#include "value.h"
-#include "vm.h"
+#include "wren_value.h"
+#include "wren_vm.h"
 
 static void* allocate(WrenVM* vm, size_t size)
 {

src/wren_value.h

@@ -3,7 +3,7 @@
 
 #include <stdint.h>
 
-#include "common.h"
+#include "wren_common.h"
 #include "wren.h"
 
 // This defines the built-in types and their core representations in memory.

src/wren_vm.c

@@ -2,10 +2,10 @@
 #include <stdio.h>
 #include <string.h>
 
-#include "common.h"
-#include "compiler.h"
-#include "vm.h"
 #include "wren.h"
+#include "wren_common.h"
+#include "wren_compiler.h"
+#include "wren_vm.h"
 #include "wren_core.h"
 
 WrenVM* wrenNewVM(WrenReallocateFn reallocateFn)

src/wren_vm.h

@@ -1,8 +1,8 @@
 #ifndef wren_vm_h
 #define wren_vm_h
 
-#include "common.h"
-#include "value.h"
+#include "wren_common.h"
+#include "wren_value.h"
 
 // TODO(bob): Make these externally controllable.
 #define STACK_SIZE 1024