started docs for non-standard control flow featurs

library/bootstrap/boot-stage1.factor

@@ -97,6 +97,13 @@ vectors words ;
         "/library/tools/annotations.factor"
         "/library/tools/inspector.factor"
         
+        "/library/help/database.factor"
+        "/library/help/stylesheet.factor"
+        "/library/help/help.factor"
+        "/library/help/markup.factor"
+        "/library/help/word-help.factor"
+        "/library/help/syntax.factor"
+        
         "/library/test/test.factor"
 
         "/library/threads.factor"
@@ -143,13 +150,6 @@ vectors words ;
         
         "/library/bootstrap/init.factor"
         
-        "/library/help/database.factor"
-        "/library/help/stylesheet.factor"
-        "/library/help/help.factor"
-        "/library/help/markup.factor"
-        "/library/help/word-help.factor"
-        "/library/help/syntax.factor"
-        
         ! This must be the last file of parsing words loaded
         "/library/syntax/parse-syntax.factor"
 
@@ -197,6 +197,7 @@ vectors words ;
 
         "/library/help/commands.factor"
 
+        "/library/continuations.facts"
         "/library/kernel.facts"
         "/library/vocabularies.facts"
         "/library/words.facts"

library/continuations.factor

@@ -13,9 +13,6 @@ USING: namespaces sequences ;
 TUPLE: continuation data call name catch ;
 
 : continuation ( -- interp )
-    #! The continuation is reified from after the *caller* of
-    #! this word returns. It must be declared inline for this
-    #! invariant to be preserved in compiled code too.
     datastack callstack dup pop* dup pop*
     namestack catchstack <continuation> ; inline
 
@@ -26,32 +23,20 @@ TUPLE: continuation data call name catch ;
     continuation-catch ; inline
 
 : ifcc ( terminator balance -- | quot: continuation -- )
-    #! Note that the branch at the end must not be optimized out
-    #! by the compiler.
     [
         continuation
         dup continuation-data f over push f swap push dup
     ] call 2swap if ; inline
 
-: callcc0 ( quot -- | quot: continuation -- )
-    #! Call a quotation with the current continuation, which may
-    #! be restored using continue.
-    [ drop ] ifcc ; inline
+: callcc0 [ drop ] ifcc ; inline
 
 : continue ( continuation -- )
-    #! Restore a continuation.
     >continuation<
     set-catchstack set-namestack set-callstack set-datastack ;
     inline
 
 : (continue-with) 9 getenv ;
 
-: callcc1 ( quot -- | quot: continuation -- )
-    #! Call a quotation with the current continuation, which may
-    #! be restored using continue-with.
-    [ drop (continue-with) ] ifcc ; inline
+: callcc1 [ drop (continue-with) ] ifcc ; inline
 
-: continue-with ( object continuation -- object )
-    #! Restore a continuation, and place the object in the
-    #! restored data stack.
-    swap 9 setenv continue ; inline
+: continue-with swap 9 setenv continue ; inline

library/continuations.facts

@@ -0,0 +1,44 @@
+USING: errors help kernel ;
+
+HELP: catchstack* "( -- catchstack )"
+{ $values { "catchstack" "a vector" } }
+{ $description "Outputs the current catchstack." } ;
+
+HELP: catchstack "( -- catchstack )"
+{ $values { "catchstack" "a vector" } }
+{ $description "Outputs a copy of the current catchstack." } ;
+
+HELP: set-catchstack "( catchstack -- )"
+{ $values { "catchstack" "a vector" } }
+{ $description "Replaces the catchstack with a copy of the given vector." } ;
+
+HELP: continuation "( -- continuation )"
+{ $values { "continuation" "a continuation" } }
+{ $description "Reifies the current continuation from the point immediately after which the caller returns." } ;
+
+HELP: >continuation< "( continuation -- data call name catch )"
+{ $values { "continuation" "a continuation" } { "data" "a vector" } { "call" "a vector" } { "name" "a vector" } { "catch" "a vector" } }
+{ $description "Takes a continuation apart into its four constituents." } ;
+
+HELP: ifcc "( terminator balance -- )"
+{ $values { "terminator" "a quotation with stack effect " { $snippet "( continuation -- )" } { "balance" "a quotation" } }
+{ $description "Reifies a continuation and passes it to " { $snippet "terminator" } ". When the continuation is restored, execution resumes; " { $snippet "terminator" } " is still on the stack and "{ $snippet "balance" } " is called." }
+{ $see-also callcc0 callcc1 } ;
+
+HELP: callcc0 "( quot -- )"
+{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } }
+{ $description "Applies the quotation to the current continuation. The " { $link continue } " word resumes the continuation." }
+{ $see-also ifcc callcc1 continue } ;
+
+HELP: callcc1 "( quot -- obj )"
+{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } { "obj" "an object provided when resuming the continuation" } }
+{ $description "Applies the quotation to the current continuation. The " { $link continue-with } " word resumes the continuation, passing a value back to the original execution context." }
+{ $see-also ifcc callcc0 continue-with } ;
+
+HELP: continue "( continuation -- )"
+{ $values { "continuation" "a continuation" } }
+{ $description "Resumes a continuation reified by " { $link callcc0 } "." } ;
+
+HELP: continue-with "( obj continuation -- )"
+{ $values { "obj" "an object to pass to the continuation's execution context" } { "continuation" "a continuation" } }
+{ $description "Resumes a continuation reified by " { $link callcc1 } ". The object remains on the stack when the continuation resumes executing." } ;

library/errors.factor

@@ -3,8 +3,6 @@
 IN: errors
 USING: kernel kernel-internals lists sequences ;
 
-! This is a very lightweight exception handling system.
-
 TUPLE: no-method object generic ;
 
 : no-method ( object generic -- ) <no-method> throw ;

library/errors.facts

@@ -0,0 +1,7 @@
+USING: errors help ;
+
+HELP: throw "( error -- )"
+{ $values { "error" "an object" } }
+{ $description "Throws an error. Execution does not continue at the point after the " { $link throw } " call. Rather, the innermost catch block is invoked, and execution continues at that point." } ;
+
+

library/help/markup.factor

@@ -179,10 +179,10 @@ DEFER: help
         terpri
     ] interleave ;
 
-: $predicate ( content -- :r)
-    { { "object" object } } $values
+: $predicate ( content -- )
+    { { "object" "an object" } } $values
     "Tests if the top of the stack is " $description
-    dup word-name a/an print-element $link "." print-element ;
+    dup first word-name a/an format* $link "." format* ;
 
 : $list ( content -- )
     terpri* [ "- " format* print-element terpri* ] each ;

library/tools/describe.factor

@@ -1,7 +1,7 @@
 ! Copyright (C) 2005 Slava Pestov.
 ! See http://factor.sf.net/license.txt for BSD license.
 IN: inspector
-USING: arrays generic hashtables io kernel kernel-internals
+USING: arrays generic hashtables help io kernel kernel-internals
 lists math prettyprint sequences strings vectors words ;
 
 GENERIC: summary ( object -- string )
@@ -83,16 +83,13 @@ DEFER: describe
 
 : describe ( object -- ) dup summary print sheet sheet. ;
 
-: word. ( word -- )
-    dup word-name swap dup [ see ] curry simple-outliner ;
-
 : sequence-outliner ( seq quot -- | quot: obj -- )
     swap [
         [ unparse-short ] keep rot dupd curry simple-outliner
     ] each-with ;
 
 : words. ( vocab -- )
-    words word-sort [ see ] sequence-outliner ;
+    words word-sort [ (help) ] sequence-outliner ;
 
 : vocabs. ( -- )
     #! Outlining word browser.