From: Tim Vaughan <tgvaughan@gmail.com>
Date: Wed, 1 Aug 2018 14:53:41 +0000 (+0200)
Subject: Added comments to continuation words.
X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=commitdiff_plain;h=c775ab2562b213ac96fe1803d4e7001a73e874a8;p=scheme.forth.jl.git

Added comments to continuation words.
---

diff --git a/src/scheme-primitives.4th b/src/scheme-primitives.4th
index c3eeb5d..dbb68bc 100644
--- a/src/scheme-primitives.4th
+++ b/src/scheme-primitives.4th
@@ -610,6 +610,14 @@ defer display
 :noname ( proc -- result )
     make-continuation
 
+    ( Note that we get to this point either when
+    make-continuation is originally called or when
+    restore-continuation is called.  Since we don't
+    want to call proc again following a restore,
+    we use the boolean values placed on the parameter
+    stack by make-continuation and restore-continuation
+    to detect which call got us here and act accordingly. )
+
     drop if
         nil cons
         2swap apply
diff --git a/src/scheme.4th b/src/scheme.4th
index 9347750..027a193 100644
--- a/src/scheme.4th
+++ b/src/scheme.4th
@@ -597,6 +597,8 @@ global-env obj!
   2drop
 ;
 
+( This word restores the return stack to that contained in the
+continuation object, and thus NEVER RETURNS. )
 : restore-return-stack ( continuation -- )
 
     continuation->rstack-list
@@ -618,6 +620,15 @@ global-env obj!
     2drop
 ;
 
+( This word restores the parameter and return stacks
+to those in the continuation object. The restoration of the 
+return stack means that execution continues at the point
+described in the continuation object, so this word NEVER RETURNS.
+
+Note that both obj and a false-obj are added to the parameter
+stack before the return stack is restored, so that make-continuation
+knows that this execution path is the result of a continuation
+restoration rather than the original call to make-continuation. )
 : restore-continuation-with-arg ( continuation obj -- )
 
     >R >R \ Store obj on return stack