compiler.tree.*: docs

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

@@ -1,15 +1,26 @@
 USING: compiler.tree help.markup help.syntax kernel sequences ;
 IN: compiler.tree.cleanup
 
+HELP: >copy
+{ $values { "node" node } { "#copy" #copy } }
+{ $description "Creates a #copy node from the inputs and outputs of a node." } ;
+
 HELP: cleanup-folding?
 { $values { "#call" #call } { "?" boolean } }
 { $description "Checks if a " { $link #call } " node can be folded." } ;
 
 HELP: cleanup-tree
 { $values { "nodes" sequence } { "nodes'" sequence } }
-{ $description "Main entry point for the cleanup-tree optimization phase." } ;
+{ $description "Main entry point for the cleanup-tree optimization phase. We don't recurse into children here, instead the methods do it since the logic is a bit more involved." } ;
+
+HELP: fold-only-branch
+{ $values { "#branch" #branch } { "node/nodes" "a " { $link node } " or a sequence of nodes" } }
+{ $description "If only one branch is live we don't need to branch at all; just drop the condition value." } ;
 
 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." ;
+"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."
+$nl
+"Main entry point:"
+{ $subsections cleanup-tree } ;
 
 ABOUT: "compiler.tree.cleanup"

basis/compiler/tree/cleanup/cleanup.factor

@@ -24,8 +24,6 @@ M: node delete-node drop ;
 GENERIC: cleanup-tree* ( node -- node/nodes )
 
 : cleanup-tree ( nodes -- nodes' )
-    ! We don't recurse into children here, instead the methods
-    ! do it since the logic is a bit more involved
     [ cleanup-tree* ] map-flat ;
 
 ! Constant folding
@@ -114,8 +112,6 @@ M: #call cleanup-tree*
     ] change-children drop ;
 
 : fold-only-branch ( #branch -- node/nodes )
-    ! If only one branch is live we don't need to branch at
-    ! all; just drop the condition value.
     dup live-children sift dup length {
         { 0 [ drop in-d>> <#drop> ] }
         { 1 [ first swap in-d>> <#drop> prefix ] }

basis/compiler/tree/propagation/constraints/constraints-docs.factor

@@ -1,11 +1,11 @@
-USING: help.markup help.syntax kernel ;
+USING: help.markup help.syntax kernel sequences ;
 IN: compiler.tree.propagation.constraints
 
 HELP: class-constraint
 { $class-description "A class constraint." } ;
 
 HELP: constraints
-{ $var-description "Maps constraints to constraints ('A implies B')" } ;
+{ $var-description "A " { $link sequence } " of assocs. They maps constraints to constraints ('A implies B')." } ;
 
 HELP: equivalence
 { $var-description "An equivalence constraint." } ;

basis/compiler/tree/propagation/nodes/nodes-docs.factor

@@ -1,10 +1,14 @@
-USING: compiler.tree help.markup help.syntax ;
+USING: assocs compiler.tree help.markup help.syntax sequences ;
 IN: compiler.tree.propagation.nodes
 
 HELP: annotate-node
 { $values { "node" node } }
 { $description "Initializes the info slot for SSA tree nodes that have it." } ;
 
+HELP: extract-value-info
+{ $values { "values" sequence } { "assoc" assoc } }
+{ $description "Creates an assoc mapping values to infos for the 'values'." } ;
+
 HELP: propagate-around
 { $values { "node" node } }
 { $description "Performs value propagation for an SSA node." } ;

basis/compiler/tree/propagation/recursive/recursive-docs.factor

@@ -0,0 +1,12 @@
+USING: compiler.tree compiler.tree.propagation.info
+compiler.tree.propagation.nodes help.markup help.syntax sequences ;
+IN: compiler.tree.propagation.recursive
+
+HELP: recursive-phi-infos
+{ $values { "node" #recursive } { "infos" sequence } }
+{ $description "The sequence of " { $link value-info-state } " that is the input to the recursive block." } ;
+
+ARTICLE: "compiler.tree.propagation.recursive" "Propagation for inline recursive combinators"
+"This vocab implements the " { $link propagate-before } ", " { $link annotate-node } " and " { $link propagate-around } " words for recursive tree nodes." ;
+
+ABOUT: "compiler.tree.propagation.recursive"

basis/compiler/tree/propagation/recursive/recursive.factor

@@ -45,7 +45,12 @@ IN: compiler.tree.propagation.recursive
     2dup [ not ] either? [ drop ] [
         2dup [ class>> null-class? ] either? [ drop ] [
             [ clone ] dip
-            [ [ drop ] [ [ [ interval>> ] bi@ ] [ drop class>> ] 2bi generalize-counter-interval ] 2bi >>interval ]
+            [
+                [ drop ] [
+                    [ [ interval>> ] bi@ ] [ drop class>> ] 2bi
+                    generalize-counter-interval
+                ] 2bi >>interval
+            ]
             [ [ drop ] [ [ slots>> ] bi@ [ generalize-counter ] 2map ] 2bi >>slots ]
             bi
         ] if

basis/compiler/tree/tree-docs.factor

@@ -1,16 +1,17 @@
-USING: assocs help.markup help.syntax kernel kernel.private quotations
-sequences stack-checker.alien stack-checker.values
+USING: alien assocs help.markup help.syntax kernel kernel.private quotations
+sequences stack-checker.alien stack-checker.inlining stack-checker.values
 stack-checker.visitor words ;
 IN: compiler.tree
 
 HELP: node
-{ $class-description "Base class for all SSA tree nodes." } ;
+{ $class-description "Base class for all SSA tree nodes. The node is an " { $link identity-tuple } " which means that two different node instances with the same attributes are not equal." } ;
 
 HELP: #alien-node
 { $class-description "Base class for alien nodes. Its " { $snippet "params" } " slot holds an instance of the " { $link alien-node-params } " class." } ;
 
 HELP: #alien-invoke
-{ $class-description "SSA tree node that calls a function in a dynamically linked library." } ;
+{ $class-description "SSA tree node that calls a function in a dynamically linked library." }
+{ $see-also alien-invoke } ;
 
 HELP: #alien-callback
 { $class-description "SSA tree node that constructs an alien callback." } ;
@@ -27,9 +28,26 @@ HELP: #call
   }
 } ;
 
+HELP: #call-recursive
+{ $class-description "In a " { $link #recursive } " block of the SSA tree, this node represents a call back to the beginning of the block." }
+{ $see-also #recursive } ;
+
 HELP: #declare
 { $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered." } ;
 
+HELP: #enter-recursive
+{ $class-description "This node works is placed first in the " { $slot "child" } " sequence for " { $link #recursive } " nodes and works like a header for it." }
+{ $see-also #recursive #return-recursive } ;
+
+HELP: #if
+{ $class-description "SSA tree node that implements conditional branching. It has the following slots:"
+  { $table
+    { { $slot "children" }
+      { "A two item " { $link sequence } ". The first item holds the instructions executed if the condition is true and the second those that are executed if it is not true." }
+    }
+  }
+} ;
+
 HELP: #introduce
 { $class-description "SSA tree node that puts an input value from the \"outside\" on the stack. It is used to \"introduce\" data stack parameter whenever they are needed. It has the following slots:"
   { $table
@@ -37,6 +55,9 @@ HELP: #introduce
   }
 } ;
 
+HELP: #phi
+{ $class-description "#phi is a SSA tree node type that unifies two branches in an " { $link #if } "." } ;
+
 HELP: #push
 { $class-description "SSA tree node that puts a literal value on the stack. It has the following slots:"
   { $table
@@ -45,6 +66,15 @@ HELP: #push
 }
 { $notes "A " { $link quotation } " is also a literal." } ;
 
+HELP: #recursive
+{ $class-description "Instruction which encodes a loop. It has the following slots:"
+  { $table
+    { { $slot "child" } { "A sequence of nodes representing the body of the loop." } }
+    { { $slot "loop?" } { "If " { $link t } ", the recursion is implemented using a jump, otherwise as a call back to the word." } }
+  }
+}
+{ $see-also inline-recursive-word } ;
+
 HELP: #shuffle
 { $class-description "SSA tree node that represents a stack shuffling operation such as " { $link swap } ". It has the following slots:"
   { $table
@@ -52,15 +82,6 @@ HELP: #shuffle
   }
 } ;
 
-HELP: #if
-{ $class-description "SSA tree node that implements conditional branching. It has the following slots:"
-  { $table
-    { { $slot "children" }
-      { "A two item " { $link sequence } ". The first item holds the instructions executed if the condition is true and the second those that are executed if it is not true." }
-    }
-  }
-} ;
-
 HELP: node,
 { $values { "node" node } }
 { $description "Emits a node to the " { $link stack-visitor } " variable." } ;
@@ -71,6 +92,13 @@ ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
   #call
   #declare
   #shuffle
+}
+"Nodes for control flow:"
+{ $subsections
+  #call-recursive
+  #enter-recursive
+  #recursive
+  #return-recursive
 } ;
 
 ABOUT: "compiler.tree"