Docs: initial docs for compiler.tree.propagation.* vocabs

diff --git a/basis/compiler/tree/propagation/info/info-docs.factor b/basis/compiler/tree/propagation/info/info-docs.factor
new file mode 100644 (file)
index 0000000..4e11f5b
--- /dev/null
+++ b/basis/compiler/tree/propagation/info/info-docs.factor
@@ -0,0 +1,21 @@
+USING: compiler.tree help.markup help.syntax sequences ;
+IN: compiler.tree.propagation.info
+
+HELP: value-info-state
+{ $class-description "Represents constraints the compiler knows about the input and output variables to an SSA tree node. It has the following slots:"
+  { $table
+    { { $slot "class" } { "Class of values the variable can take." } }
+    { { $slot "interval" } { "Range of values the variable can take." } }
+    { { $slot "literal" } { "Literal value, if present." } }
+    { { $slot "literal?" } { "Whether the value of the variable is known at compile-time or not." } }
+    { { $slot "slots" } { "If the value is a literal tuple or fixed length type, then slots is a " { $link sequence } " of " { $link value-info-state } " encoding what is known about its slots at compile-time." } }
+  }
+} ;
+
+HELP: node-input-infos
+{ $values { "node" node } { "seq" sequence } }
+{ $description "Lists the value infos for the input variables of an SSA tree node." } ;
+
+HELP: node-output-infos
+{ $values { "node" node } { "seq" sequence } }
+{ $description "Lists the value infos for the output variables of an SSA tree node." } ;

diff --git a/basis/compiler/tree/propagation/known-words/known-words-docs.factor b/basis/compiler/tree/propagation/known-words/known-words-docs.factor
new file mode 100644 (file)
index 0000000..b79f331
--- /dev/null
+++ b/basis/compiler/tree/propagation/known-words/known-words-docs.factor
@@ -0,0 +1,37 @@
+USING: classes compiler.tree.propagation.info help.markup help.syntax math
+math.intervals ;
+IN: compiler.tree.propagation.known-words
+
+HELP: binary-op-class
+{ $values { "info1" value-info-state } { "info2" value-info-state } { "newclass" class } }
+{ $description "Given two value infos return the math class which is large enough for both of them." }
+{ $examples
+  { $example
+    "USING: compiler.tree.propagation.known-words compiler.tree.propagation.info math prettyprint ;"
+    "bignum real [ <class-info> ] bi@ binary-op-class ."
+    "real"
+  }
+} ;
+
+HELP: unary-op-class
+{ $values { "info" value-info-state } { "newclass" class } }
+{ $description "Returns the smallest math class large enough to hold values of the value infos class." }
+{ $see-also binary-op-class } ;
+
+HELP: number-valued
+{ $values
+  { "class" class } { "interval" interval }
+  { "class'" class } { "interval'" interval }
+}
+{ $description "Ensure that the class is a subclass of " { $link number } "." } ;
+
+HELP: fits-in-fixnum?
+{ $values { "interval" interval } { "?" "a boolean" } }
+{ $description "Checks if the interval is a subset of the " { $link fixnum } " interval. Used to see if arithmetic may overflow." }
+{ $examples
+  { $example
+    "USING: compiler.tree.propagation.known-words prettyprint ;"
+    "clear full-interval fits-in-fixnum? ."
+    "f"
+  }
+} ;

diff --git a/basis/compiler/tree/propagation/nodes/nodes-docs.factor b/basis/compiler/tree/propagation/nodes/nodes-docs.factor
new file mode 100644 (file)
index 0000000..92886f4
--- /dev/null
+++ b/basis/compiler/tree/propagation/nodes/nodes-docs.factor
@@ -0,0 +1,6 @@
+USING: compiler.tree help.markup help.syntax ;
+IN: compiler.tree.propagation.nodes
+
+HELP: annotate-node
+{ $values { "node" node } }
+{ $description "Initializes the info slot for SSA tree nodes that have it." } ;

diff --git a/basis/compiler/tree/propagation/propagation-docs.factor b/basis/compiler/tree/propagation/propagation-docs.factor
new file mode 100644 (file)
index 0000000..9e7a689
--- /dev/null
+++ b/basis/compiler/tree/propagation/propagation-docs.factor
@@ -0,0 +1,50 @@
+USING: help.markup help.syntax literals multiline ;
+IN: compiler.tree.propagation
+
+STRING: propagate-ex
+USING: compiler.tree.builder compiler.tree.propagation math prettyprint ;
+[ 3 + ] build-tree propagate third .
+T{ #call
+    { word + }
+    { in-d V{ 9450187 9450186 } }
+    { out-d { 9450188 } }
+    { info
+        H{
+            {
+                9450186
+                T{ value-info-state
+                    { class fixnum }
+                    { interval
+                        T{ interval
+                            { from ~array~ }
+                            { to ~array~ }
+                        }
+                    }
+                    { literal 3 }
+                    { literal? t }
+                }
+            }
+            {
+                9450187
+                T{ value-info-state
+                    { class object }
+                    { interval full-interval }
+                }
+            }
+            {
+                9450188
+                T{ value-info-state
+                    { class number }
+                    { interval full-interval }
+                }
+            }
+        }
+    }
+}
+;
+
+HELP: propagate
+{ $values { "nodes" "a sequence of nodes" } }
+{ $description "Performs the propagation pass of the AST optimization. All nodes info slots are initialized here." }
+{ $examples { $unchecked-example $[ propagate-ex ] }
+} ;