1077

21 files changed, 49 insertions, 16 deletions

diff --git a/cpp/010vm b/cpp/010vm
index db274622..de50bde0 100644
--- a/cpp/010vm
+++ b/cpp/010vm
@@ -132,10 +132,10 @@ enum primitive_recipes {
   MAX_PRIMITIVE_RECIPES,
 };
 :(code)
-// It's all very well to construct recipes out of other recipes, but we need
-// to know how to do *something* out of the box. For the following
-// recipes there are only codes, no entries in the book, because mu just knows
-// what to do for them.
+//: It's all very well to construct recipes out of other recipes, but we need
+//: to know how to do *something* out of the box. For the following
+//: recipes there are only codes, no entries in the book, because mu just knows
+//: what to do for them.
 void setup_recipes() {
   Recipe.clear();  Recipe_number.clear();
   Recipe_number["idle"] = IDLE;
diff --git a/cpp/011load b/cpp/011load
index 9978ac8c..3dea0d66 100644
--- a/cpp/011load
+++ b/cpp/011load
@@ -1,4 +1,5 @@
 //: It's often convenient to express recipes in a textual fashion.
+
 :(scenarios add_recipes)
 :(scenario first_recipe)
 recipe main [
diff --git a/cpp/013literal_string b/cpp/013literal_string
index f56cb928..8dc8c1b5 100644
--- a/cpp/013literal_string
+++ b/cpp/013literal_string
@@ -1,11 +1,10 @@
-//: Some instructions can take string literals for convenience.
+//: For convenience, some instructions will take literal arrays of characters (strings).
 //:
 //: Instead of quotes, we'll use [] to delimit strings. That'll reduce the
 //: need for escaping since we can support nested brackets. And we can also
 //: imagine that 'recipe' might one day itself be defined in mu, doing its own
 //: parsing.
 
-//: First extend the mu parser to support string literals.
 :(scenario "string_literal")
 recipe main [
   1:address:array:character <- new [abc def]
diff --git a/cpp/020run b/cpp/020run
index 91e242a7..1de1c6ae 100644
--- a/cpp/020run
+++ b/cpp/020run
@@ -1,3 +1,14 @@
+//: Once a recipe is loaded, we need to run it.
+//:
+//: So far we've seen recipes as lists of instructions, and instructions point
+//: at other recipes. To kick things off mu needs to know how to run certain
+//: 'primitive' recipes. That will then give the ability to run recipes
+//: containing these primitives.
+//:
+//: This layer defines a skeleton with just two primitive recipes: IDLE which
+//: does nothing, and COPY, which can copy numbers from one memory location to
+//: another. Later layers will add more primitives.
+
 :(scenarios run)
 :(scenario copy_literal)
 recipe main [
@@ -66,6 +77,7 @@ void run(routine rr) {
 //: Some helpers.
 //: We'll need to override these later as we change the definition of routine.
 //: Important that they return referrences into the routine.
+
 inline size_t& running_at(routine& rr) {
   return rr.running_at;
 }
@@ -115,9 +127,8 @@ void load(string filename) {
 load("core.mu");
 recently_added_recipes.clear();  // freeze everything so it doesn't get cleared by tests
 
-//: helper for tests
-
 :(code)
+// helper for tests
 void run(string form) {
   vector<recipe_number> tmp = add_recipes(form);
   transform_all();
diff --git a/cpp/021arithmetic b/cpp/021arithmetic
index 08647cbc..15c5d9f3 100644
--- a/cpp/021arithmetic
+++ b/cpp/021arithmetic
@@ -1,5 +1,6 @@
+//: Arithmetic primitives.
+
 :(before "End Primitive Recipe Declarations")
-// Arithmetic ops.
 ADD,
 :(before "End Primitive Recipe Numbers")
 Recipe_number["add"] = ADD;
diff --git a/cpp/022boolean b/cpp/022boolean
index 6c677f7e..044a3b2b 100644
--- a/cpp/022boolean
+++ b/cpp/022boolean
@@ -1,5 +1,6 @@
+//: Boolean primitives.
+
 :(before "End Primitive Recipe Declarations")
-// Boolean ops.
 AND,
 :(before "End Primitive Recipe Numbers")
 Recipe_number["and"] = AND;
diff --git a/cpp/023jump b/cpp/023jump
index 669c7258..128b3924 100644
--- a/cpp/023jump
+++ b/cpp/023jump
@@ -1,5 +1,6 @@
+//: Jump primitives.
+
 :(before "End Primitive Recipe Declarations")
-// Jump ops.
 JUMP,
 :(before "End Primitive Recipe Numbers")
 Recipe_number["jump"] = JUMP;
diff --git a/cpp/024compare b/cpp/024compare
index 145feaa2..8675c36a 100644
--- a/cpp/024compare
+++ b/cpp/024compare
@@ -1,5 +1,6 @@
+//: Comparison primitives.
+
 :(before "End Primitive Recipe Declarations")
-// Comparison ops.
 EQUAL,
 :(before "End Primitive Recipe Numbers")
 Recipe_number["equal"] = EQUAL;
diff --git a/cpp/025trace b/cpp/025trace
index bd05d848..247a9dc7 100644
--- a/cpp/025trace
+++ b/cpp/025trace
@@ -1,3 +1,5 @@
+//: Allow mu programs to log facts just like we've been doing in C++ so far.
+
 :(scenario "trace")
 recipe main [
   trace [foo], [this is a trace in mu]
diff --git a/cpp/030container b/cpp/030container
index fcdd82f9..0e013900 100644
--- a/cpp/030container
+++ b/cpp/030container
@@ -1,4 +1,5 @@
 //: Containers contain a fixed number of elements of different types.
+
 :(before "End Mu Types Initialization")
 //: We'll use this container as a running example, with two integer elements.
 int point = Type_number["point"] = Next_type_number++;
diff --git a/cpp/031address b/cpp/031address
index 22355fc6..801459f6 100644
--- a/cpp/031address
+++ b/cpp/031address
@@ -1,5 +1,6 @@
 //: Instructions can read from addresses pointing at other locations using the
 //: 'deref' property.
+
 :(scenario "copy_indirect")
 recipe main [
   1:address:integer <- copy 2:literal
diff --git a/cpp/032array b/cpp/032array
index 3bdfe95e..fbb5ed7b 100644
--- a/cpp/032array
+++ b/cpp/032array
@@ -1,4 +1,5 @@
 //: Arrays contain a variable number of elements of the same type.
+
 :(scenario copy_array)
 # Arrays can be copied around with a single instruction just like integers,
 # no matter how large they are.
diff --git a/cpp/035call b/cpp/035call
index 3683db12..21d07b18 100644
--- a/cpp/035call
+++ b/cpp/035call
@@ -1,4 +1,5 @@
-//: So far the recipes we define can't run each other. Let's change that.
+//: So far the recipes we define can't run each other. Let's fix that.
+
 :(scenario "calling_recipe")
 recipe main [
   f
@@ -46,7 +47,7 @@ inline vector<instruction>& steps(routine& rr) {
 
 :(replace{} "default:" following "End Primitive Recipe Implementations")
 default: {
-  // not a primitive; try to look for a matching recipe
+  // not a primitive; try to look up the book of recipes
   if (Recipe.find(instructions[pc].operation) == Recipe.end()) {
     raise << "undefined operation " << instructions[pc].operation << ": " << instructions[pc].name << '\n';
     break;
diff --git a/cpp/036call_ingredient b/cpp/036call_ingredient
index ecf53539..9b85aa55 100644
--- a/cpp/036call_ingredient
+++ b/cpp/036call_ingredient
@@ -1,5 +1,6 @@
 //: Calls can take ingredients just like primitives. To access a recipe's
 //: ingredients, use 'next-ingredient'.
+
 :(scenario "next_ingredient")
 recipe main [
   f 2:literal
diff --git a/cpp/037call_reply b/cpp/037call_reply
index b44552cc..2e5459d4 100644
--- a/cpp/037call_reply
+++ b/cpp/037call_reply
@@ -1,4 +1,5 @@
-//: Calls can also generate results, using 'reply'.
+//: Calls can also generate products, using 'reply'.
+
 :(scenario "reply")
 recipe main [
   3:integer, 4:integer <- f 2:literal
@@ -37,7 +38,7 @@ case REPLY: {
   break;
 }
 
-//: Results can include containers and exclusive containers, addresses and arrays.
+//: Products can include containers and exclusive containers, addresses and arrays.
 :(scenario "reply_container")
 recipe main [
   3:point <- f 2:literal
diff --git a/cpp/050scenario b/cpp/050scenario
index c595ce82..9c29d971 100644
--- a/cpp/050scenario
+++ b/cpp/050scenario
@@ -1,4 +1,5 @@
 //: Allow tests to be written in mu files.
+
 :(before "End Types")
 struct scenario {
   string name;
diff --git a/cpp/051scenario_test.mu b/cpp/051scenario_test.mu
index bf30ce8f..024086a9 100644
--- a/cpp/051scenario_test.mu
+++ b/cpp/051scenario_test.mu
@@ -1,4 +1,5 @@
 # tests for 'scenario' in previous layer
+
 scenario first_scenario_in_mu [
   run [
     1:integer <- add 2:literal, 2:literal
diff --git a/cpp/052scenario_trace b/cpp/052scenario_trace
index 90dab204..4436ee3f 100644
--- a/cpp/052scenario_trace
+++ b/cpp/052scenario_trace
@@ -1,3 +1,6 @@
+//: Support a scenario [ ... ] form at the top level so we can start creating
+//: scenarios in mu just like we do in C++.
+
 :(before "End scenario Fields")
 vector<pair<string, string> > trace_checks;
 vector<pair<string, string> > trace_negative_checks;
diff --git a/cpp/053scenario_trace_test.mu b/cpp/053scenario_trace_test.mu
index abf0ef9a..8016bbfb 100644
--- a/cpp/053scenario_trace_test.mu
+++ b/cpp/053scenario_trace_test.mu
@@ -1,4 +1,5 @@
 # tests for trace-checking scenario in previous layer
+
 scenario first_scenario_checking_trace [
   run [
     1:integer <- add 2:literal, 2:literal
diff --git a/cpp/054closure_name b/cpp/054closure_name
index 76a1bdd7..b2ea3cc5 100644
--- a/cpp/054closure_name
+++ b/cpp/054closure_name
@@ -2,6 +2,7 @@
 //: spaces together. When a variable has a property of /space:1, it looks up
 //: the variable in the chained/surrounding space. /space:2 looks up the
 //: surrounding space of the surrounding space, etc.
+
 :(scenario "closure")
 recipe main [
   default-space:address:space <- new location:type, 30:literal
@@ -32,6 +33,7 @@ recipe increment-counter [
 
 //: To make this work, compute the recipe that provides names for the
 //: surrounding space of each recipe. This must happen before transform_names.
+
 :(before "End Globals")
 unordered_map<recipe_number, recipe_number> Surrounding_space;
 
diff --git a/cpp/060string.mu b/cpp/060string.mu
index e85dc083..a437c24f 100644
--- a/cpp/060string.mu
+++ b/cpp/060string.mu
@@ -1,3 +1,5 @@
+# Some useful helpers for dealing with strings
+
 recipe string-equal [
   default-space:address:space <- new location:type, 30:literal
   a:address:array:character <- next-ingredient