compiler.cfg.*: a bunch of new docstrings and other doc fixes

basis/compiler/cfg/block-joining/block-joining-docs.factor

@@ -5,6 +5,10 @@ HELP: join-block?
 { $values { "bb" basic-block } { "?" "a boolean" } }
 { $description "Whether the block can be joined with its predecessor or not." } ;
 
+HELP: join-blocks
+{ $values { "cfg" cfg } }
+{ $description "A compiler pass when optimizing the cfg." } ;
+
 ARTICLE: "compiler.cfg.block-joining" "Block Joining"
 "Joining blocks that are not calls and are connected by a single CFG edge. This pass does not update " { $link ##phi } " nodes and should therefore only run before stack analysis." ;
 

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

@@ -61,6 +61,10 @@ HELP: emit-call
 }
 { $see-also call-height } ;
 
+HELP: emit-loop-call
+{ $values { "basic-block" basic-block } }
+{ $description "Sets the given block as the successor of the current block. Then ends the block." } ;
+
 HELP: emit-node
 { $values { "node" node } }
 { $description "Emits CFG instructions for the given SSA node." } ;

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

@@ -0,0 +1,11 @@
+USING: compiler.cfg help.markup help.syntax math sequences ;
+IN: compiler.cfg.dce
+
+HELP: eliminate-dead-code
+{ $values { "cfg" cfg } }
+{ $description "Even though we don't use predecessors directly, we depend on the predecessors pass updating phi nodes to remove dead inputs." } ;
+
+ARTICLE: "compiler.cfg.dce" "Dead code elimination"
+"Eliminates dead code." ;
+
+ABOUT: "compiler.cfg.dce"

basis/compiler/cfg/dce/dce.factor

@@ -117,9 +117,6 @@ M: insn live-insn? drop t ;
 
 : eliminate-dead-code ( cfg -- )
     init-dead-code
-    ! Even though we don't use predecessors directly, we depend
-    ! on the predecessors pass updating phi nodes to remove dead
-    ! inputs.
     {
         [ needs-predecessors ]
         [ [ [ build-liveness-graph ] each ] simple-analysis ]

basis/compiler/cfg/gc-checks/gc-checks-docs.factor

@@ -4,25 +4,9 @@ IN: compiler.cfg.gc-checks
 
 <PRIVATE
 
-HELP: insert-gc-checks
-{ $values { "cfg" cfg }  }
-{ $description "Inserts gc checks in each " { $link basic-block } " in the cfg where they are needed." } ;
-
-HELP: insert-gc-check?
-{ $values { "bb" basic-block } { "?" "a boolean" } }
-{ $description "Whether to insert a gc check in the block or not." } ;
-
-HELP: blocks-with-gc
-{ $values { "cfg" cfg } { "bbs" "a " { $link sequence } " of " { $link basic-block } } }
-{ $description "Lists all basic blocks in the cfg that needs gc checks." } ;
-
-HELP: allocation-size*
-{ $values { "insn" insn } { "n" number } }
-{ $description "Number of bytes allocated by the given instruction." } ;
-
 HELP: allocation-size
 { $values { "insns" { $link sequence } " of " { $link insn } } { "n" number } }
-{ $description "Calculates the total number of bytes allocated by the block." }
+{ $description "Calculates the total number of bytes allocated by the instructions in a block." }
 { $examples
   { $unchecked-example
     "USING: accessors compiler.cfg.debugger compiler.cfg.gc-checks.private kernel prettyprint sequences ;"
@@ -31,11 +15,34 @@ HELP: allocation-size
   }
 } ;
 
-PRIVATE>
+HELP: allocation-size*
+{ $values { "insn" insn } { "n" number } }
+{ $description "Number of bytes allocated by the given instruction." } ;
 
-ARTICLE: "compiler.cfg.gc-checks" "Garbage collection check insertion"
-"This pass runs after representation selection, since it needs to know which vregs can contain tagged pointers." ;
+HELP: blocks-with-gc
+{ $values { "cfg" cfg } { "bbs" "a " { $link sequence } " of " { $link basic-block } } }
+{ $description "Lists all basic blocks in the cfg that needs gc checks." } ;
+
+HELP: gc-check-offsets
+{ $values { "insns" sequence } { "seq" sequence } }
+{ $description "A basic block is divided into sections by " { $link ##call } " and " { $link ##phi } " instructions. For every section with at least one allocation, record the offset of its first instruction  in a sequence." } ;
+
+HELP: insert-gc-check?
+{ $values { "bb" basic-block } { "?" "a boolean" } }
+{ $description "Whether to insert a gc check in the block or not." } ;
+
+HELP: insert-gc-checks
+{ $values { "cfg" cfg }  }
+{ $description "Inserts gc checks in each " { $link basic-block } " in the cfg where they are needed." } ;
+
+PRIVATE>
 
 HELP: process-block
 { $values { "bb" basic-block } }
 { $description "Process a block that needs a gc check. New blocks are allocated and connected for the gc branches." } ;
+
+
+ARTICLE: "compiler.cfg.gc-checks" "Garbage collection check insertion"
+"This pass runs after representation selection, since it needs to know which vregs can contain tagged pointers." ;
+
+ABOUT: "compiler.cfg.gc-checks"

basis/compiler/cfg/gc-checks/gc-checks.factor

@@ -29,10 +29,6 @@ M: ##allocation gc-check-offsets* 3drop t ;
 M: insn gc-check-offsets* 2drop ;
 
 : gc-check-offsets ( insns -- seq )
-    ! A basic block is divided into sections by call and phi
-    ! instructions. For every section with at least one
-    ! allocation, record the offset of its first instruction
-    ! in a sequence.
     [
         [ 0 f ] dip
         [ gc-check-offsets* ] each-index
@@ -122,9 +118,7 @@ M: ##box-displaced-alien allocation-size* drop 5 cells ;
 
 PRIVATE>
 
-:: insert-gc-checks ( cfg -- )
-    cfg blocks-with-gc [
-        cfg needs-predecessors
-        [ process-block ] each
-        cfg cfg-changed
-    ] unless-empty ;
+: insert-gc-checks ( cfg -- )
+    [ needs-predecessors ]
+    [ blocks-with-gc [ process-block ] each ]
+    [ cfg-changed ] tri ;

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

@@ -0,0 +1,11 @@
+USING: compiler.tree help.markup help.syntax ;
+IN: compiler.cfg.intrinsics.allot
+
+HELP: emit-<tuple-boa>
+{ $values { "node" node } }
+{ $description "Emits optimized cfg instructions for building and allocating tuples." } ;
+
+ARTICLE: "compiler.cfg.intrinsics.allot" "Generating instructions for inline memory allocation"
+"Generating instructions for inline memory allocation" ;
+
+ABOUT: "compiler.cfg.intrinsics.allot"

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

@@ -12,7 +12,7 @@ HELP: begin-stack-analysis
 { $see-also height-state } ;
 
 HELP: end-stack-analysis
-{ $description "Ends the stack analysis of the current cfg." } ;
+{ $description "Ends the stack analysis of the current cfg. This is the last step of the cfg construction (but comes before all optimization passes)." } ;
 
 HELP: adjust-d
 { $values { "n" number } }
@@ -26,7 +26,7 @@ HELP: store-vregs
   { "vregs" "a " { $link sequence } " of vregs" }
   { "loc-class" "either " { $link ds-loc } " or " { $link rs-loc } }
 }
-{ $description "Stores one or more virtual register values on the data or retain stack. The " { $link replace-mapping } " dynamic variable is modified but the " { $link height-state } " is not touched" } ;
+{ $description "Stores one or more virtual register values on the data or retain stack. The " { $link replaces } " dynamic variable is modified but the " { $link height-state } " is not touched" } ;
 
 HELP: 2inputs
 { $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } }