compiler.*: more docs

basis/compiler/cfg/cfg-docs.factor

@@ -78,3 +78,10 @@ HELP: cfg-changed
 HELP: spill-offset
 { $values { "n" integer } { "offset" integer } }
 { $description "Offset in the current " { $link stack-frame } " to byte at index 'n' in the spill area." } ;
+
+ARTICLE: "compiler.cfg" "Control Flow Graph IR"
+"The compiler.cfg vocab and subvocabs implements the part of the optimizing compiler that analyzes code in the CFG format. The vocab " { $vocab-link "compiler.cfg.builder" } " defines words for building the CFG from SSA IR and the rest of the vocabs in the hierarchy optimization steps that are then applied to it. The graph is then passed to the " { $vocab-link "compiler.codegen" } " vocab which emits machine code."
+$nl
+"The main datatype in the vocab is the " { $link cfg } " tuple. It represents the CFG of a Factor word. The cfg tuple has a slot 'entry' pointing to a " { $link basic-block } ". This block in turn points to other basic blocks, and together they form the call flow graph of the word." ;
+
+ABOUT: "compiler.cfg"

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

@@ -62,6 +62,10 @@ HELP: ##allot
   }
 } ;
 
+HELP: ##bit-count
+{ $class-description "Specialized instruction for counting the number of lit bits in an integer." }
+{ $see-also %bit-count } ;
+
 HELP: ##box
 { $class-description
   "This instruction boxes a value into a tagged pointer."
@@ -521,6 +525,7 @@ $nl
 { $subsections
   ##add-vector
   ##add-sub-vector
+  ##bit-count
   ##compare-float-ordered-branch
   ##div-vector
   ##horizontal-add-vector

basis/compiler/cfg/representations/conversion/conversion-docs.factor

@@ -1,6 +1,14 @@
 USING: cpu.architecture help.markup help.syntax make ;
 IN: compiler.cfg.representations.conversion
 
+HELP: emit-conversion
+{ $values
+  { "dst" "vreg" }
+  { "src" "vreg" }
+  { "dst-rep" representation }
+  { "src-rep" representation }
+} { $description "Emits an instruction converting a virtual register from one representation to another." } ;
+
 HELP: tagged>rep
 { $values { "dst" "vreg" } { "src" "vreg" } { "rep" representation } }
 { $description "Emits an instruction to the current " { $link make }

basis/compiler/codegen/labels/labels.factor

@@ -37,7 +37,6 @@ TUPLE: label-fixup-state { label label } { class integer } { offset integer } ;
     [ [ compute-relative-label ] map concat ]
     bi* ;
 
-! Binary literals
 SYMBOL: binary-literal-table
 
 : add-binary-literal ( obj -- label )

basis/compiler/crossref/crossref-docs.factor

@@ -1,4 +1,4 @@
-USING: assocs help.markup help.syntax sequences words ;
+USING: assocs help.markup help.syntax kernel sequences words ;
 IN: compiler.crossref
 
 HELP: compiled-crossref
@@ -8,6 +8,10 @@ HELP: delete-compiled-xref
 { $values { "word" word } }
 { $description "Deletes cross-referencing data for a word. Used when the optimizing compiler forgets a word." } ;
 
+HELP: dependencies-satisfied?
+{ $values { "word" word } { "cache" assoc } { "?" boolean } }
+{ $description "Checks if all the words dependencies are satisfied or not." } ;
+
 HELP: load-dependencies
 { $values { "word" word } { "seq" sequence } }
 { $description "Outputs a sequence of the words dependencies." } ;
@@ -19,3 +23,8 @@ HELP: remove-xref
 HELP: store-dependencies
 { $values { "word" word } { "assoc" assoc } }
 { $description "Stores the dependencies in 'assoc' in the word attribute \"dependencies\"." } ;
+
+ARTICLE: "compiler.crossref"  "Crossreferencing word dependencies."
+"A vocab that keeps track on how words depends on each other and their dependence types." ;o
+
+ABOUT: "compiler.crossref"

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

@@ -0,0 +1,18 @@
+USING: compiler.tree help.markup help.syntax sequences ;
+IN: compiler.tree.propagation.branches
+
+HELP: child-constraints
+{ $values { "node" node } { "seq" sequence } }
+{ $description "For conditionals, an assoc of child node # --> constraint." } ;
+
+HELP: condition-value
+{ $var-description "When propagating an " { $link #if } " node, this variable holds the value that is being dispatched on." } ;
+
+HELP: live-branches
+{ $values { "#branch" #branch } { "indices" sequence } }
+{ $description "Outputs a sequence of true and false values indicating which of the branches that are possibly live." } ;
+
+ARTICLE: "compiler.tree.propagation.branches" "Sparse propagation for branches"
+"Sparse propagation for branches" ;
+
+ABOUT: "compiler.tree.propagation.branches"

basis/compiler/tree/propagation/branches/branches.factor

@@ -8,7 +8,6 @@ namespaces sequences stack-checker.branches ;
 FROM: sets => union ;
 IN: compiler.tree.propagation.branches
 
-! For conditionals, an assoc of child node # --> constraint
 GENERIC: child-constraints ( node -- seq )
 
 M: #if child-constraints

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

@@ -1,5 +1,6 @@
-USING: compiler.tree compiler.tree.propagation.info help.markup
+USING: classes compiler.tree compiler.tree.propagation.info
-help.syntax quotations sequences words ;
+help.markup help.syntax quotations sequences
+stack-checker.dependencies words ;
 IN: compiler.tree.propagation.simple
 
 HELP: call-outputs-quot
@@ -15,8 +16,7 @@ HELP: propagate-predicate
 { $values { "#call" #call } { "word" word } { "infos" sequence } }
 { $description "We need to force the caller word to recompile when the class is redefined, since now we're making assumptions but the class definition itself." } ;
 
-ARTICLE: "compiler.tree.propagation.simple"
+ARTICLE: "compiler.tree.propagation.simple" "Propagation for straight-line code"
-"Propagation for straight-line code"
 "Propagation for straight-line code" ;
 
 ABOUT: "compiler.tree.propagation.simple"

basis/compiler/tree/tree-docs.factor

@@ -33,7 +33,11 @@ HELP: #call-recursive
 { $see-also #recursive } ;
 
 HELP: #declare
-{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered." } ;
+{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered. It has the following slots:"
+  { $table
+    { { $slot "declaration" } { { $link assoc } " that maps values to the types they are declared as." } }
+  }
+} ;
 
 HELP: #enter-recursive
 { $class-description "This node works is placed first in the 'child' " { $link sequence } " for " { $link #recursive } " nodes and works like a header for it." }
@@ -99,6 +103,21 @@ ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
   #enter-recursive
   #recursive
   #return-recursive
+  #terminate
+}
+"Nodes for alien ffi:"
+{ $subsections
+  #alien-node
+  #alien-invoke
+  #alien-indirect
+  #alien-assembly
+  #alien-callback
+}
+"Nodes for branching:"
+{ $subsections
+  #dispatch
+  #if
+  #phi
 } ;
 
 ABOUT: "compiler.tree"