1151

3 files changed, 32 insertions, 10 deletions

diff --git a/cpp/000organization b/cpp/000organization
index 939324ef..bf017d16 100644
--- a/cpp/000organization
+++ b/cpp/000organization
@@ -11,14 +11,17 @@
 //: cycle. Doing one well makes it easier to do the other.
 //:
 //: Lower down, this file contains a legal, bare-bones C++ program. It doesn't
-//: do anything yet; subsequent files will add behaviors by inserting lines
-//: into it with directives like:
+//: do anything yet; subsequent files or 'layers' will contain directives to
+//: inserting lines into it. For example:
 //:   :(after "more events")
 //: This will insert the following lines after a line in the program containing
 //: the words "more events".
-//: A simple tool will 'tangle' these files according to the directives, though
-//: it'll drop these comments starting with a '//:' prefix that only make sense
-//: in the context of layers.
+//:
+//: A simple tool will 'tangle' all the layers together according to the
+//: directives into a single source file containing all the code for the
+//: project, and then feed the source file to the compiler. (It'll drop these
+//: comments starting with a '//:' prefix that only make sense in the context
+//: of layers.)
 //:
 //: Directives free up the programmer to order code for others to read rather
 //: than as forced by the computer or compiler. Each individual feature can be
@@ -65,8 +68,7 @@
 //:   ============
 //:
 //: Here's part of a layer in color: http://i.imgur.com/0eONnyX.png. Directives
-//: are shaded dark. Notice the references to waypoints lower down in this
-//: file.
+//: are shaded dark.
 //:
 //: Layers do more than just shuffle code around. Past the initial skeleton of
 //: this program (currently 00*-02*), it ought to be possible to stop loading
diff --git a/cpp/001help b/cpp/001help
index c3ce7874..18d7efa6 100644
--- a/cpp/001help
+++ b/cpp/001help
@@ -1,3 +1,6 @@
+//: Everything this project/binary supports.
+//: This should give you a sense for what to look forward to in later layers.
+
 :(before "End Commandline Parsing")
 if (argc <= 1 || is_equal(argv[1], "--help")) {
   // this is the functionality later layers will provide
@@ -12,6 +15,15 @@ if (argc <= 1 || is_equal(argv[1], "--help")) {
   return 0;
 }
 
+//:: Helper function used by the above fragment of code (and later layers too,
+//:: who knows?).
+//: The :(code) directive appends function definitions to the end of the
+//: project. Regardless of where functions are defined, we can call them
+//: anywhere we like as long as we format the function header in a specific
+//: way: put it all on a single line without indent, end the line with ') {'
+//: and no trailing whitespace. As long as functions uniformly start this
+//: way, our makefile contains a little command to automatically generate
+//: declarations for them.
 :(code)
 bool is_equal(char* s, const char* lit) {
   return strncmp(s, lit, strlen(lit)) == 0;
diff --git a/cpp/makefile b/cpp/makefile
index 75ed8424..98982f08 100644
--- a/cpp/makefile
+++ b/cpp/makefile
@@ -17,9 +17,7 @@ tangle/tangle:
 termbox/libtermbox.a:
 	cd termbox && make
 
-# auto-generated files; by convention they end in '_list'.
 .PHONY: autogenerated_lists test valgrind clena
-autogenerated_lists: mu.cc function_list test_list
 
 test: mu
 	./mu test
@@ -27,11 +25,21 @@ test: mu
 valgrind: mu
 	valgrind --leak-check=yes ./mu test
 
+# auto-generated files; by convention they end in '_list'.
+autogenerated_lists: mu.cc function_list test_list
+
+# autogenerated list of function declarations, so I can define them in any order
 function_list: mu.cc
-	# declarations for lines starting with non-space and ending with ') {', except methods
+	# functions start out unindented, have all args on the same line, and end in ') {'
+	#  																		ignore methods
 	@grep -h "^[^[:space:]#].*) {" mu.cc |grep -v ":.*(" |perl -pwe 's/ {.*/;/' > function_list
+	# occasionally we need to modify a declaration in a later layer without messing with ugly unbalanced brackets
+	# assume such functions move the '{' to column 0 of the very next line
+	@grep -v "^#line" mu.cc |grep -B1 "^{" |grep -v "^{" |perl -pwe 's/$$/;/' >> function_list
+	# test functions
 	@grep -h "^\s*TEST(" mu.cc |perl -pwe 's/^\s*TEST\((.*)\)$$/void test_$$1();/' >> function_list
 
+# autogenerated list of tests to run
 test_list: mu.cc
 	@grep -h "^\s*void test_" mu.cc |perl -pwe 's/^\s*void (.*)\(\) {.*/$$1,/' > test_list
 	@grep -h "^\s*TEST(" mu.cc |perl -pwe 's/^\s*TEST\((.*)\)$$/test_$$1,/' >> test_list