Docs: stub docs for some compiler-related words

diff --git a/basis/compiler/compiler-docs.factor b/basis/compiler/compiler-docs.factor
index 76c93a842286d763981d10cc88a25d652dfe72be..c15f54229c9c54d1f2aa96721fb68fcaf75f33f5 100644 (file)
--- a/basis/compiler/compiler-docs.factor
+++ b/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

diff --git a/basis/compiler/tree/builder/builder-docs.factor b/basis/compiler/tree/builder/builder-docs.factor
index 83093470c9e0168731429b3f789938718186dc5a..5f761be68153a4a66f1a1c6ffff45079bfee03b4 100644 (file)
--- a/basis/compiler/tree/builder/builder-docs.factor
+++ b/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
+    ]
+  }
+} ;

diff --git a/basis/compiler/tree/cleanup/cleanup-docs.factor b/basis/compiler/tree/cleanup/cleanup-docs.factor
new file mode 100644 (file)
index 0000000..4f09dea
--- /dev/null
+++ b/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." } ;

diff --git a/basis/compiler/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor
new file mode 100644 (file)
index 0000000..70eb40b
--- /dev/null
+++ b/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." } ;

diff --git a/basis/stack-checker/values/values-docs.factor b/basis/stack-checker/values/values-docs.factor
new file mode 100644 (file)
index 0000000..9745d94
--- /dev/null
+++ b/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." } ;

diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor
index 4b72acc0f2a02458374b07a69cb507bd063b03e0..c08bf38d627e9f8cca521b3869270f76e7b77454 100644 (file)
--- a/core/sequences/sequences-docs.factor
+++ b/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 -- ... )" } } }