Adding a sample file showing objects/prototypes. Documenting.

sample/objects.fin

@@ -0,0 +1,48 @@
+' define a singleton object for the Car "type". this object will be
+' the factory for all other cars.
+def Car <- Object copyWith: {
+    ' define the car prototype. all cars will derive from this
+    def _prototype <- Object copyWith: {
+        ' all cars have accessors for their make and model
+        .addMethod: "make" body: { _make }
+        .addMethod: "model" body: { _model }
+
+        .addMethod: "toString" body: {
+            "This car is a " + _make + " " + _model + "."
+        }
+    }
+
+    ' define a constructor method on the factory.
+    .addMethod: "make:model:" body: {
+        |make model|
+
+        ' the constructor simply derives a new car from the car
+        ' prototype and then stores the make and model in it
+        _prototype copyWith: {
+            def _make <- make
+            def _model <- model
+        }
+        ' like ruby, the last expression in the method is implicitly
+        ' the returned value
+    }
+
+    ' expose the prototype. this lets us add features to all cars
+    .addMethod: "prototype" body: { _prototype }
+}
+
+' now lets make a car
+def jetta <- Car make: "volkswagen" model: "jetta"
+
+' and call a method on its prototype, which in turn references the
+' specific car's state
+writeLine: jetta toString
+
+' now let's try adding something to the car prototype. first we'll
+' check to see that it isn't there
+writeLine: jetta shortName ' this should write Nil
+
+' now we'll add a method to the prototype
+Car prototype addMethod: "shortName" body: { _make + " " + _model }
+
+' now lets call it on jetta and see if we can find it
+writeLine: jetta shortName

src/Repl.h

@@ -4,12 +4,16 @@
 
 namespace Finch
 {
+    // A simple read/eval/print loop. Calling Run() will create a new Finch
+    // environment, read an expression from stdin, evaluate it, and repeat
+    // until the user quits by calling "Ether quit".
     class Repl
     {
     public:
         Repl()
         {}
 
+        // Runs the REPL. This function will not return until the user quits.
         void Run();
 
     private:

src/Script.h

@@ -10,10 +10,15 @@ namespace Finch
     class Environment;
     class Object;
 
+    // Static class for loading and executing Finch code stored in script files.
     class Script
     {
     public:
+        // Loads and runs the script at the given path in its own environment.
         static Ref<Object> Run(String fileName);
+
+        // Loads and runs the script at the given path in the given existing
+        // environment.
         static Ref<Object> Run(String fileName, Environment & env);
 
     private:

src/Stack.h

@@ -26,13 +26,15 @@ namespace Finch
         // Gets the maximum number of items the stack can hold.
         int Capacity() const { return Size; }
 
+        // Pushes the given item onto the top of the stack.
         void Push(const T & item)
         {
             ASSERT(mCount < Capacity(), "Cannot push onto a full stack.");
 
             mItems[mCount++] = item;
         }
 
+        // Pops the top item off the stack.
         T Pop()
         {
             ASSERT(mCount > 0, "Cannot pop an empty stack.");

src/Syntax/FinchParser.h

@@ -28,6 +28,7 @@ namespace Finch
         Ref<Expr> ParseLine();
 
     private:
+        // The grammar productions, from lowest to highest precedence.
         Ref<Expr> Expression();
         Ref<Expr> Sequence();
         Ref<Expr> Variable();

src/Syntax/ILineReader.h

@@ -8,8 +8,9 @@
 namespace Finch
 {
     // Interface for a class that reads a series of lines of text from some
-    // source. Used to abstract where the Lexer gets it Finch source from so
-    // that we can use it both for the Repl and for parsing entire source files.
+    // source. Used to abstract where the Lexer gets it Finch source code from
+    // so that we can use it both for the Repl and for parsing entire source
+    // files.
     class ILineReader
     {
     public:

src/Syntax/Parser.h

@@ -40,6 +40,7 @@ namespace Finch
 
         ITokenSource & mTokens;
 
+        // The 2 here is the maximum number of lookahead tokens.
         Queue<Ref<Token>, 2> mRead;
 
         NO_COPY(Parser);

src/Syntax/Token.h

@@ -40,7 +40,8 @@ namespace Finch
     class Token
     {
     public:
-        // virtual constructors
+        // Factory methods to construct tokens of different types with
+        // different data.
         static Ref<Token> New(TokenType type);
         static Ref<Token> New(TokenType type, const String & text);
         static Ref<Token> New(TokenType type, double number);