Docs: stub docs for some compiler-related words

basis/compiler/compiler-docs.factor

@@ -19,7 +19,7 @@ ARTICLE: "compiler-usage" "Calling the optimizing compiler"
 "More words can be found in " { $link "compilation-units" } "." ;
 
 ARTICLE: "compiler-impl" "Compiler implementation"
-"The " { $vocab-link "compiler" } "vocabulary, in addition to providing the user-visible words of the compiler, implements the main compilation loop."
+"The " { $vocab-link "compiler" } " vocabulary, in addition to providing the user-visible words of the compiler, implements the main compilation loop."
 $nl
 "Once compiled, a word is added to the assoc stored in the " { $link compiled } " variable. When compilation is complete, this assoc is passed to " { $link modify-code-heap } "."
 $nl

basis/compiler/tree/builder/builder-docs.factor

@@ -1,5 +1,5 @@
-USING: help.markup help.syntax sequences quotations words 
-compiler.tree stack-checker.errors ;
+USING: compiler.tree help.markup help.syntax literals quotations sequences
+stack-checker.errors words ;
 IN: compiler.tree.builder
 
 HELP: build-tree
@@ -10,4 +10,20 @@ HELP: build-tree
 
 HELP: build-sub-tree
 { $values { "in-d" "a sequence of values" } { "out-d" "a sequence of values" } { "word/quot" { $or word quotation } } { "nodes/f" { $maybe "a sequence of nodes" } } }
-{ $description "Attempts to construct tree SSA IR from a quotation, starting with an initial data stack of values from the call site. Outputs " { $link f } " if stack effect inference fails." } ;
+{ $description "Attempts to construct tree SSA IR from a quotation, starting with an initial data stack of values from the call site. Outputs " { $link f } " if stack effect inference fails." }
+{ $examples
+  { $unchecked-example
+    ! The out-d numbers are unpredicable.
+    "USING: compiler.tree.builder math prettyprint ;"
+    "{ \"x\" } { \"y\" } [ 4 * ] build-sub-tree ."
+    $[
+        {
+            "V{"
+            "    T{ #push { literal 4 } { out-d { 1 } } }"
+            "    T{ #call { word * } { in-d V{ \"x\" 1 } } { out-d { 2 } } }"
+            "    T{ #copy { in-d V{ 2 } } { out-d { \"y\" } } }"
+            "}"
+        } "\n" join
+    ]
+  }
+} ;

basis/compiler/tree/cleanup/cleanup-docs.factor

@@ -0,0 +1,8 @@
+USING: help.markup help.syntax ;
+IN: compiler.tree.cleanup
+
+ARTICLE: "compiler.tree.cleanup" "Cleanup Phase"
+"A phase run after propagation to finish the job, so to speak. Codifies speculative inlining decisions, deletes branches marked as never taken, and flattens local recursive blocks that do not call themselves." ;
+
+HELP: cleanup
+{ $description "Main entry point for the cleanup optimization phase." } ;

basis/compiler/tree/tree-docs.factor

@@ -0,0 +1,23 @@
+USING: assocs help.markup help.syntax kernel sequences stack-checker.visitor ;
+IN: compiler.tree
+
+HELP: #call
+{ $class-description "SSA tree node that calls a word." } ;
+
+HELP: #introduce
+{ $class-description "SSA tree node that puts an input value from the \"outside\" on the stack." } ;
+
+HELP: #push
+{ $class-description "SSA tree node that puts a literal value on the stack." }
+{ $notes "A quotation is also a literal." } ;
+
+HELP: #shuffle
+{ $class-description "SSA tree node that represents a stack shuffling operation such as " { $link swap } ". It has the following slots:"
+  { $table
+    { { $slot "mapping" } { "An " { $link assoc } " that shows how the shuffle output values (the keys) correspond to their inputs (the values)." } }
+  }
+} ;
+
+HELP: node,
+{ $values { "node" node } }
+{ $description "Emits a node to the " { $link stack-visitor } " variable." } ;

basis/stack-checker/values/values-docs.factor

@@ -0,0 +1,6 @@
+USING: help.markup help.syntax math quotations sequences words ;
+IN: stack-checker.values
+
+HELP: <value>
+{ $values { "value" number } }
+{ $description "Outputs a series of monotonically increasing numbers." } ;

core/sequences/sequences-docs.factor

@@ -285,7 +285,14 @@ HELP: set-array-nth
 
 HELP: collect
 { $values { "n" "a non-negative integer" } { "quot" { $quotation "( ... n -- ... value )" } } { "into" "a sequence of length at least " { $snippet "n" } } }
-{ $description "A primitive mapping operation that applies a quotation to all integers from 0 up to but not including " { $snippet "n" } ", and collects the results in a new array. User code should use " { $link map } " instead." } ;
+{ $description "A primitive mapping operation that applies a quotation to all integers from 0 up to but not including " { $snippet "n" } ", and collects the results in a new array. User code should use " { $link map } " instead." }
+{ $examples
+  { $example
+    "USING: kernel math.parser prettyprint sequences sequences.private ;"
+    "10 [ number>string ] 10 f new-sequence [ collect ] keep ."
+    "{ \"0\" \"1\" \"2\" \"3\" \"4\" \"5\" \"6\" \"7\" \"8\" \"9\" }"
+  }
+} ;
 
 HELP: each
 { $values { "seq" sequence } { "quot" { $quotation "( ... x -- ... )" } } }