compiler.cfg.*: more docs

basis/compiler/cfg/builder/builder.factor

@@ -5,13 +5,9 @@ compiler.cfg.builder.blocks compiler.cfg.comparisons
 compiler.cfg.hats compiler.cfg.instructions
 compiler.cfg.intrinsics compiler.cfg.registers
 compiler.cfg.stacks compiler.cfg.stacks.local compiler.tree
-cpu.architecture fry kernel make math namespaces sequences words
+cpu.architecture fry kernel make math namespaces sequences words ;
-;
 IN: compiler.cfg.builder
 
-! Convert tree SSA IR to CFG IR. The result is not in SSA form; this is
-! constructed later by calling compiler.cfg.ssa.construction:construct-ssa.
-
 SYMBOL: procedures
 SYMBOL: loops
 
@@ -51,6 +47,7 @@ GENERIC: emit-node ( node -- )
 
 : (build-cfg) ( nodes word label -- )
     [
+
         begin-word
         emit-nodes
     ] with-cfg-builder ;
@@ -164,8 +161,9 @@ M: #push emit-node
 ! we try not to introduce useless ##peeks here, since this reduces
 ! the accuracy of global stack analysis.
 
+
+
 : make-input-map ( #shuffle -- assoc )
-    ! Assoc maps high-level IR values to stack locations.
     [
         [ in-d>> <reversed> [ <ds-loc> swap ,, ] each-index ]
         [ in-r>> <reversed> [ <rs-loc> swap ,, ] each-index ] bi

basis/compiler/cfg/intrinsics/misc/misc-docs.factor

@@ -0,0 +1,6 @@
+USING: compiler.tree help.markup help.syntax kernel.private words ;
+IN: compiler.cfg.intrinsics.misc
+
+HELP: emit-context-object
+{ $values { "node" node } }
+{ $description "Emits intrinsic code for a call to the " { $link context-object } " primitive." } ;

basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor

@@ -0,0 +1,6 @@
+USING: compiler.cfg compiler.cfg.linear-scan.allocation help.markup
+help.syntax sequences ;
+
+HELP: (allocate-registers)
+{ $values { "unhandled-intervals" "stuff" } { "unhandled-sync-points" "stuff" } }
+{ $description "Register allocation works by emptying the unhandled intervals and sync points." } ;

basis/compiler/cfg/stacks/height/height.factor

@@ -4,7 +4,6 @@ USING: accessors assocs compiler.cfg.registers fry kernel math
 namespaces ;
 IN: compiler.cfg.stacks.height
 
-! Global stack height tracking done while constructing CFG.
 SYMBOLS: ds-heights rs-heights ;
 
 : record-stack-heights ( ds-height rs-height bb -- )

basis/compiler/cfg/stacks/local/local-docs.factor

@@ -51,7 +51,7 @@ HELP: height-changes
 } ;
 
 HELP: emit-changes
-{ $description "! Insert height and stack changes prior to the last instruction." } ;
+{ $description "Insert height and stack changes prior to the last instruction." } ;
 
 HELP: inc-d
 { $values { "n" number } }

basis/compiler/cfg/stacks/stacks-docs.factor

@@ -10,10 +10,16 @@ HELP: begin-stack-analysis
 { $description "Initializes a set of variables related to stack analysis of Factor words." }
 { $see-also current-height } ;
 
+HELP: end-stack-analysis
+{ $description "Ends the stack analysis of the current cfg." } ;
+
 HELP: adjust-d
 { $values { "n" number } }
 { $description "Changes the height of the current data stack." } ;
 
+HELP: ds-drop
+{ $description "Used to signal to the stack analysis that the datastacks height is decreased by one." } ;
+
 HELP: ds-store
 { $values { "vreg" "a " { $link sequence } " of vregs." } }
 { $description "Registers that a sequence of vregs are stored at at each corresponding index of the data stack." } ;

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

@@ -0,0 +1,6 @@
+USING: compiler.tree help.markup help.syntax ;
+IN: compiler.tree.debugger
+
+HELP: #>r?
+{ $values { "#shuffle" #shuffle } { "?" "a boolean" } }
+{ $description "True if the #shuffle copies an item from the data stack to the retain stack." } ;

basis/compiler/tree/tree-docs.factor

@@ -1,5 +1,5 @@
-USING: assocs help.markup help.syntax kernel sequences stack-checker.alien
+USING: assocs help.markup help.syntax kernel quotations sequences
-stack-checker.visitor words ;
+stack-checker.alien stack-checker.visitor words ;
 IN: compiler.tree
 
 HELP: node
@@ -29,7 +29,7 @@ HELP: #introduce
 
 HELP: #push
 { $class-description "SSA tree node that puts a literal value on the stack." }
-{ $notes "A quotation is also a literal." } ;
+{ $notes "A " { $link 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:"