From 669bb0a77eaf13264bfeb9ac38f1e5240b9b3f58 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Bj=C3=B6rn=20Lindqvist?= Date: Thu, 24 Apr 2014 21:35:04 +0200 Subject: [PATCH] Docs: stub docs for some compiler-related words --- basis/compiler/compiler-docs.factor | 2 +- .../compiler/tree/builder/builder-docs.factor | 22 +++++++++++++++--- .../compiler/tree/cleanup/cleanup-docs.factor | 8 +++++++ basis/compiler/tree/tree-docs.factor | 23 +++++++++++++++++++ basis/stack-checker/values/values-docs.factor | 6 +++++ core/sequences/sequences-docs.factor | 9 +++++++- 6 files changed, 65 insertions(+), 5 deletions(-) create mode 100644 basis/compiler/tree/cleanup/cleanup-docs.factor create mode 100644 basis/compiler/tree/tree-docs.factor create mode 100644 basis/stack-checker/values/values-docs.factor diff --git a/basis/compiler/compiler-docs.factor b/basis/compiler/compiler-docs.factor index 76c93a8422..c15f54229c 100644 --- 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 83093470c9..5f761be681 100644 --- 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 index 0000000000..4f09dea269 --- /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 index 0000000000..70eb40bbfc --- /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 index 0000000000..9745d94f5d --- /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: +{ $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 4b72acc0f2..c08bf38d62 100644 --- 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 -- ... )" } } } -- 2.34.1