Docs: for compiler.cfg.* vocabs

basis/compiler/cfg/builder/blocks/blocks-docs.factor

@@ -1,5 +1,22 @@
-USING: compiler.cfg help.markup help.syntax ;
+USING: compiler.cfg compiler.tree help.markup help.syntax math ;
 IN: compiler.cfg.builder.blocks
 
+HELP: initial-basic-block
+{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ;
+
+HELP: begin-basic-block
+{ $description "Terminates the current block and initializes a new " { $link basic-block } " to begin outputting instructions to. The new block is included in the old blocks " { $slot "successors" } "." } ;
+
 HELP: make-kill-block
 { $description "Marks the current " { $link basic-block } " being processed as a kill block." } ;
+
+HELP: call-height
+{ $values { "#call" #call } { "n" number } }
+{ $description "Calculates how many items a " { $link #call } " will add or remove from the data stack." }
+{ $examples
+  { $example
+    "USING: compiler.cfg.builder.blocks prettyprint ;"
+    "[ 3append ] build-tree second call-height ."
+    "-2"
+  }
+} ;

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

@@ -1,6 +1,63 @@
-USING: compiler.tree help.markup help.syntax sequences words ;
+USING: assocs compiler.cfg compiler.cfg.builder.blocks
+compiler.cfg.stacks.local compiler.tree help.markup help.syntax literals math
+multiline sequences words ;
 IN: compiler.cfg.builder
 
+<<
+STRING: ex-emit-call
+USING: compiler.cfg.builder kernel make prettyprint ;
+begin-stack-analysis initial-basic-block \ dummy 3 [ emit-call ] { } make drop
+current-height basic-block [ get . ] bi@ .
+T{ current-height { d 3 } }
+T{ basic-block
+    { id 134 }
+    { successors
+        V{
+            T{ basic-block
+                { id 135 }
+                { instructions
+                    V{
+                        T{ ##call { word dummy } }
+                        T{ ##branch }
+                    }
+                }
+                { successors V{ T{ basic-block { id 136 } } } }
+                { kill-block? t }
+            }
+        }
+    }
+}
+;
+
+STRING: ex-make-input-map
+USING: compiler.cfg.builder prettyprint ;
+T{ #shuffle { in-d { 37 81 92 } } } make-input-map .
+H{
+    { 81 T{ ds-loc { n 1 } } }
+    { 37 T{ ds-loc { n 2 } } }
+    { 92 T{ ds-loc } }
+}
+;
+>>
+
+HELP: procedures
+{ $var-description "Used as a temporary storage for the current cfg during construction of all cfgs." } ;
+
+HELP: make-input-map
+{ $values { "#call" #call } { "assoc" assoc } }
+{ $description "Creates an " { $link assoc } " that maps input values to the shuffle operation to stack locations." }
+{ $examples { $unchecked-example $[ ex-make-input-map ] } } ;
+
+
+HELP: emit-call
+{ $values { "word" word } { "height" number } }
+{ $description "Emits a call to the given word to the " { $link cfg } " being constructed. \"height\" is the number of items being added to or removed from the data stack. Side effects of the word is that it modifies the \"basic-block\" and " { $link current-height } " variables." }
+{ $examples
+  "In this example, a call to a dummy word is emitted which pushes three items onto the stack."
+  { $unchecked-example $[ ex-emit-call ] }
+}
+{ $see-also call-height } ;
+
 HELP: emit-node
 { $values { "node" node } }
 { $description "Emits some kind of code for the node." } ;

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

@@ -0,0 +1,12 @@
+USING: compiler.cfg compiler.cfg.registers help.markup help.syntax math ;
+IN: compiler.cfg.stacks.height
+
+HELP: record-stack-heights
+{ $values { "ds-height" number } { "rs-height" number } { "bb" basic-block } }
+{ $description "Does something." } ;
+
+HELP: ds-heights
+{ $var-description "Assoc that records the data stacks height at the entry of each " { $link basic-block } "." } ;
+
+HELP: rs-heights
+{ $var-description "Assoc that records the retain stacks height at the entry of each " { $link basic-block } "." } ;

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

@@ -0,0 +1,14 @@
+USING: compiler.cfg.stacks.local help.markup help.syntax math sequences ;
+IN: compiler.cfg.stacks
+
+HELP: begin-stack-analysis
+{ $description "Initializes a set of variables related to stack analysis of Factor words." }
+{ $see-also current-height } ;
+
+HELP: adjust-d
+{ $values { "n" number } }
+{ $description "Changes the height of the current data stack." } ;
+
+HELP: rs-store
+{ $values { "vregs" "a " { $link sequence } " of vregs." } }
+{ $description "Stores one or more virtual register values on the retain stack. This modifies the " { $link current-height } " dynamic variable." } ;