compiler.tree.*: new docs

basis/compiler/tree/def-use/def-use-docs.factor

@@ -0,0 +1,11 @@
+USING: compiler.tree help.markup help.syntax sequences ;
+IN: compiler.tree.def-use
+
+HELP: node-defs-values
+{ $values { "node" node } { "values" sequence } }
+{ $description "The sequence of values the node introduces." } ;
+
+ARTICLE: "compiler.tree.def-use" "Def/use chain construction"
+"Def/use chain construction" ;
+
+ABOUT: "compiler.tree.def-use"

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

@@ -0,0 +1,19 @@
+USING: help.markup help.syntax math sequences ;
+IN: compiler.tree.propagation.copy
+
+HELP: compute-phi-equiv
+{ $values { "inputs" sequence } { "outputs" sequence } }
+{ $description "An output is a copy of every input if all inputs are copies of the same original value." } ;
+
+HELP: copies
+{ $var-description "Mapping from values to their canonical leader" } ;
+
+HELP: resolve-copy
+{ $values { "copy" integer } { "val" integer } }
+{ $description "Gets the original definer of this SSA value." } ;
+
+ARTICLE: "compiler.tree.propagation.copy"
+"Copy propagation"
+"Two values are copy-equivalent if they are always identical at run-time (\"DS\" relation). This is just a weak form of value numbering." ;
+
+ABOUT: "compiler.tree.propagation.copy"

basis/compiler/tree/propagation/copy/copy.factor

@@ -5,11 +5,6 @@ compiler.utilities grouping kernel namespaces sequences sets
 stack-checker.branches ;
 IN: compiler.tree.propagation.copy
 
-! Two values are copy-equivalent if they are always identical
-! at run-time ("DS" relation). This is just a weak form of
-! value numbering.
-
-! Mapping from values to their canonical leader
 SYMBOL: copies
 
 : resolve-copy ( copy -- val ) copies get compress-path ;
@@ -31,8 +26,6 @@ GENERIC: compute-copy-equiv* ( node -- )
 M: #renaming compute-copy-equiv* inputs/outputs are-copies-of ;
 
 : compute-phi-equiv ( inputs outputs -- )
-    #! An output is a copy of every input if all inputs are
-    #! copies of the same original value.
     [
         swap remove-bottom resolve-copies
         dup [ f ] [ all-equal? ] if-empty

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

@@ -1,4 +1,4 @@
-USING: compiler.tree help.markup help.syntax sequences ;
+USING: compiler.tree help.markup help.syntax math sequences ;
 IN: compiler.tree.propagation.info
 
 HELP: node-input-infos
@@ -9,6 +9,10 @@ HELP: node-output-infos
 { $values { "node" node } { "seq" sequence } }
 { $description "Lists the value infos for the output variables of an SSA tree node." } ;
 
+HELP: value-info
+{ $values { "value" integer } { "info" value-info-state } }
+{ $description "Gets the value info for the given SSA value. If none is found then a null empty interval is returned." } ;
+
 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
@@ -18,7 +22,18 @@ HELP: value-info-state
     { { $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." } }
   }
+  "Don't mutate value infos you receive, always construct new ones. We don't declare the slots read-only to allow cloning followed by writing, and to simplify constructors."
 } ;
 
 HELP: value-infos
 { $var-description "Assoc stack of current value --> info mapping" } ;
+
+ARTICLE: "compiler.tree.propagation.info" "Value info data type and operations"
+"Querying words:"
+{ $subsections
+  node-input-infos
+  node-output-infos
+  value-info
+} ;
+
+ABOUT: "compiler.tree.propagation.info"

basis/compiler/tree/propagation/info/info.factor

@@ -22,10 +22,6 @@ M: ratio eql? over ratio? [ = ] [ 2drop f ] if ;
 M: float eql? over float? [ [ double>bits ] same? ] [ 2drop f ] if ;
 M: complex eql? over complex? [ = ] [ 2drop f ] if ;
 
-! Value info represents a set of objects. Don't mutate value infos
-! you receive, always construct new ones. We don't declare the
-! slots read-only to allow cloning followed by writing, and to
-! simplify constructors.
 TUPLE: value-info-state
 class
 interval

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

@@ -1,10 +1,6 @@
 USING: compiler.tree help.markup help.syntax kernel quotations words ;
 IN: compiler.tree.propagation.inlining
 
-HELP: custom-inlining?
-{ $values { "word" word } { "quot/f" "a quotation or " { $link f } } }
-{ $description "Returns the custom inlining " { $link quotation } " for a word if it has one." } ;
-
 HELP: (do-inlining)
 { $values { "#call" #call } { "word" word } { "?" boolean } }
 { $description
@@ -13,6 +9,18 @@ HELP: (do-inlining)
   "If the generic was defined in an outer compilation unit, then it doesn't have a definition yet; the definition is built at the end of the compilation unit. We do not attempt inlining at this stage since the stack discipline is not finalized yet, so dispatch# might return an out of bounds value. This case comes up if a parsing word calls the compiler at parse time (doing so is discouraged, but it should still work.)"
 } ;
 
+HELP: custom-inlining?
+{ $values { "word" word } { "quot/f" "a quotation or " { $link f } } }
+{ $description "Returns the custom inlining " { $link quotation } " for a word if it has one." } ;
+
+HELP: do-inlining
+{ $values { "#call" #call } { "word" word } { "?" boolean } }
+{ $description "Performs inlining of the word in the #call node. If there's a custom inlining hook, it is permitted to return f, which means that we try the normal inlining heuristic." } ;
+
+HELP: inline-math-method
+{ $values { "#call" #call } { "word" word } { "?" boolean } }
+{ $description "Inlines a generic math word." } ;
+
 ARTICLE: "compiler.tree.propagation.inlining" "Method inlining and dispatch elimination"
 "Splicing nodes:"
 { $subsections splicing-call open-code-#call splicing-body } ;

basis/compiler/tree/propagation/inlining/inlining.factor

@@ -113,9 +113,6 @@ SYMBOL: history
     } cond ;
 
 : do-inlining ( #call word -- ? )
-    #! Note the logic here: if there's a custom inlining hook,
-    #! it is permitted to return f, which means that we try the
-    #! normal inlining heuristic.
     [
         dup custom-inlining? [ 2dup inline-custom ] [ f ] if
         [ 2drop t ] [ (do-inlining) ] if

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

@@ -4,3 +4,7 @@ IN: compiler.tree.propagation.nodes
 HELP: annotate-node
 { $values { "node" node } }
 { $description "Initializes the info slot for SSA tree nodes that have it." } ;
+
+HELP: propagate-around
+{ $values { "node" node } }
+{ $description "Performs value propagation for an SSA node." } ;

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

@@ -0,0 +1,18 @@
+USING: compiler.tree compiler.tree.propagation.info help.markup
+help.syntax quotations sequences words ;
+IN: compiler.tree.propagation.simple
+
+HELP: call-outputs-quot
+{ $values { "#call" #call } { "word" word } { "infos" sequence } }
+{ $description "Calls the word's \"outputs\" " { $link quotation } " to determine the output sequence of value infos, given the input sequence." } ;
+
+HELP: output-value-infos
+{ $values { "#call" #call } { "word" word } { "infos" sequence } }
+{ $description "Computes what the output value infos for a #call node should be." }
+{ $see-also value-info-state } ;
+
+ARTICLE: "compiler.tree.propagation.simple"
+"Propagation for straight-line code"
+"Propagation for straight-line code" ;
+
+ABOUT: "compiler.tree.propagation.simple"

basis/compiler/tree/propagation/simple/simple.factor

@@ -11,8 +11,6 @@ continuations fry kernel sequences stack-checker.dependencies
 words ;
 IN: compiler.tree.propagation.simple
 
-! Propagation for straight-line code.
-
 M: #introduce propagate-before
     out-d>> [ object-info swap set-value-info ] each ;
 
@@ -46,7 +44,7 @@ M: anonymous-intersection add-depends-on-class
 M: #declare propagate-before
     #! We need to force the caller word to recompile when the
     #! classes mentioned in the declaration are redefined, since
-    #! now we're making assumptions but their definitions.
+    #! now we're making assumptions about their definitions.
     declaration>> [
         [ add-depends-on-class ]
         [ <class-info> swap refine-value-info ]

basis/compiler/tree/tuple-unboxing/tuple-unboxing-docs.factor

@@ -0,0 +1,7 @@
+USING: compiler.tree.escape-analysis help.markup help.syntax ;
+IN: compiler.tree.tuple-unboxing
+
+ARTICLE: "compiler.tree.tuple-unboxing" "Tuple unboxing"
+"This pass must run after " { $link escape-analysis } "." ;
+
+ABOUT: "compiler.tree.tuple-unboxing"

basis/compiler/tree/tuple-unboxing/tuple-unboxing.factor

@@ -9,8 +9,6 @@ sequences slots.private stack-checker.branches
 stack-checker.values vectors ;
 IN: compiler.tree.tuple-unboxing
 
-! This pass must run after escape analysis
-
 GENERIC: unbox-tuples* ( node -- node/nodes )
 
 : unbox-output? ( node -- values )