From 49620728e805a3bbc3477c14b8b6ef7e2b5d3ead Mon Sep 17 00:00:00 2001
From: "Kartik K. Agaram" <vc@akkartik.com>
Date: Mon, 12 Dec 2016 10:01:12 -0800
Subject: 3707

Be more disciplined about tagging 2 different concepts in the codebase:

a) Use the phrase "later layers" to highlight places where a layer
doesn't have the simplest possible self-contained implementation.

b) Use the word "hook" to point out functions that exist purely to
provide waypoints for extension by future layers.

Since both these only make sense in the pre-tangled representation of
the codebase, using '//:' and '#:' comments to get them stripped out of
tangled output.

(Though '#:' comments still make it to tangled output at the moment.
Let's see if we use it enough to be worth supporting. Scenarios are
pretty unreadable in tangled output anyway.)
---
 020run.cc | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

(limited to '020run.cc')

diff --git a/020run.cc b/020run.cc
index 54b19c98..82cba458 100644
--- a/020run.cc
+++ b/020run.cc
@@ -63,7 +63,7 @@ void run(const recipe_ordinal r) {
 }
 
 void run_current_routine() {
-  while (should_continue_running(Current_routine)) {  // beware: later layers modify Current_routine here
+  while (should_continue_running(Current_routine)) {  // beware: may modify Current_routine
     // Running One Instruction
     if (current_instruction().is_label) { ++current_step_index();  continue; }
     trace(Initial_callstack_depth + Trace_stream->callstack_depth, "run") << to_string(current_instruction()) << end();
@@ -106,6 +106,7 @@ void run_current_routine() {
   stop_running_current_routine:;
 }
 
+//: hook replaced in a later layer
 bool should_continue_running(const routine* current_routine) {
   assert(current_routine == Current_routine);  // argument passed in just to make caller readable above
   return !Current_routine->completed();
@@ -117,29 +118,34 @@ bool should_copy_ingredients() {
 }
 
 //: Some helpers.
-//: We'll need to override these later as we change the definition of routine.
-//: Important that they return referrences into the routine.
+//: Important that they return references into the current routine.
 
+//: hook replaced in a later layer
 int& current_step_index() {
   return Current_routine->running_step_index;
 }
 
+//: hook replaced in a later layer
 const string& current_recipe_name() {
   return get(Recipe, Current_routine->running_recipe).name;
 }
 
+//: hook replaced in a later layer
 const recipe& current_recipe() {
   return get(Recipe, Current_routine->running_recipe);
 }
 
+//: hook replaced in a later layer
 const instruction& current_instruction() {
   return get(Recipe, Current_routine->running_recipe).steps.at(Current_routine->running_step_index);
 }
 
+//: hook replaced in a later layer
 bool routine::completed() const {
   return running_step_index >= SIZE(get(Recipe, running_recipe).steps);
 }
 
+//: hook replaced in a later layer
 const vector<instruction>& routine::steps() const {
   return get(Recipe, running_recipe).steps;
 }
-- 
cgit 1.4.1-2-gfad0