compiler.tree.*: more compiler tree docs

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

@@ -0,0 +1,11 @@
+USING: assocs compiler.tree help.markup help.syntax kernel ;
+IN: compiler.tree.finalization
+
+ARTICLE: "compiler.tree.finalization" "Final pass cleans up high-level IR"
+"This is a late-stage optimization. See the vocab " { $vocab-link "compiler.tree.late-optimizations" } "."
+$nl
+"This pass runs after propagation, so that it can expand type predicates; these cannot be expanded before propagation since we need to see 'fixnum?' instead of 'tag 0 eq?' and so on, for semantic reasoning."
+$nl
+"We also delete empty stack shuffles and copies to facilitate tail call optimization in the code generator." ;
+
+ABOUT: "compiler.tree.finalization"

basis/compiler/tree/finalization/finalization.factor

@@ -8,17 +8,6 @@ kernel math.partial-dispatch memoize sequences
 stack-checker.dependencies words ;
 IN: compiler.tree.finalization
 
-! This is a late-stage optimization.
-! See the comment in compiler.tree.late-optimizations.
-
-! This pass runs after propagation, so that it can expand
-! type predicates; these cannot be expanded before
-! propagation since we need to see 'fixnum?' instead of
-! 'tag 0 eq?' and so on, for semantic reasoning.
-
-! We also delete empty stack shuffles and copies to facilitate
-! tail call optimization in the code generator.
-
 GENERIC: finalize* ( node -- nodes )
 
 : finalize ( nodes -- nodes' ) [ finalize* ] map-nodes ;

basis/compiler/tree/late-optimizations/late-optimizations-docs.factor

@@ -0,0 +1,7 @@
+USING: assocs compiler.tree help.markup help.syntax kernel ;
+IN: compiler.tree.late-optimizations
+
+ARTICLE: "compiler.tree.late-optimizations" "Utilities used by several optimization passes run in the later stages"
+"Late optimizations modify the tree such that stack flow information is no longer accurate, since we punt in " { $link splice-quot } " and don't update everything that we should; this simplifies the code, improves performance, and we don't need the stack flow information after this pass anyway." ;
+
+ABOUT: "compiler.tree.late-optimizations"

basis/compiler/tree/late-optimizations/late-optimizations.factor

@@ -6,12 +6,6 @@ compiler.tree.normalization compiler.tree.propagation
 compiler.tree.recursive namespaces sequences ;
 IN: compiler.tree.late-optimizations
 
-! Late optimizations modify the tree such that stack flow
-! information is no longer accurate, since we punt in
-! 'splice-quot' and don't update everything that we should;
-! this simplifies the code, improves performance, and we
-! don't need the stack flow information after this pass anyway.
-
 : splice-quot ( quot -- nodes )
     [
         build-tree

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

@@ -0,0 +1,12 @@
+USING: assocs compiler.tree help.markup help.syntax kernel ;
+IN: compiler.tree.normalization
+
+ARTICLE: "compiler.tree.normalization" "Normalize IR created by high level IR builder to simplify subsequent passes"
+"A transform pass done before optimization can begin to fix up some oddities in the tree output by the stack checker:"
+{ $list
+  {
+      "We rewrite the code so that all " { $link #introduce } " nodes are replaced with a single one, at the beginning of a program. This simplifies subsequent analysis." }
+  { "We normalize " { $link #call-recursive } " as follows. The stack checker says that the inputs of a #call-recursive are the entire stack at the time of the call. This is a conservative estimate; we don't know the exact number of stack values it touches until the " { $link #return-recursive } " node has been visited, because of row polymorphism. So in the normalize pass, we split a #call-recursive into a #copy of the unchanged values and a #call-recursive with trimmed inputs and outputs." }
+} ;
+
+ABOUT: "compiler.tree.normalization"

basis/compiler/tree/normalization/normalization.factor

@@ -7,22 +7,6 @@ kernel math math.order namespaces sequences
 stack-checker.backend stack-checker.branches ;
 IN: compiler.tree.normalization
 
-! A transform pass done before optimization can begin to
-! fix up some oddities in the tree output by the stack checker:
-!
-! - We rewrite the code so that all #introduce nodes are
-! replaced with a single one, at the beginning of a program.
-! This simplifies subsequent analysis.
-!
-! - We normalize #call-recursive as follows. The stack checker
-! says that the inputs of a #call-recursive are the entire stack
-! at the time of the call. This is a conservative estimate; we
-! don't know the exact number of stack values it touches until
-! the #return-recursive node has been visited, because of row
-! polymorphism. So in the normalize pass, we split a
-! #call-recursive into a #copy of the unchanged values and a
-! #call-recursive with trimmed inputs and outputs.
-
 GENERIC: normalize* ( node -- node' )
 
 SYMBOL: introduction-stack

basis/compiler/tree/tree-docs.factor

@@ -1,5 +1,5 @@
 USING: assocs help.markup help.syntax kernel quotations sequences
-stack-checker.alien stack-checker.visitor words ;
+stack-checker.alien stack-checker.values stack-checker.visitor words ;
 IN: compiler.tree
 
 HELP: node
@@ -25,10 +25,18 @@ HELP: #call
 } ;
 
 HELP: #introduce
-{ $class-description "SSA tree node that puts an input value from the \"outside\" on the stack." } ;
+{ $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
+    { { $slot "out-d" } { "Array of values of the parameters being introduced." } }
+  }
+} ;
 
 HELP: #push
-{ $class-description "SSA tree node that puts a literal value on the stack." }
+{ $class-description "SSA tree node that puts a literal value on the stack. It has the following slots:"
+  { $table
+    { { $slot "out-d" } { "A one item array containing the " { $link <value> } " of the literal being pushed." } }
+  }
+}
 { $notes "A " { $link quotation } " is also a literal." } ;
 
 HELP: #shuffle