Docs: mostly fixes for doc errors found by help lint

basis/compiler/cfg/cfg-docs.factor

@@ -1,11 +1,13 @@
-USING: compiler.cfg help.markup help.syntax vectors words ;
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax vectors
+words ;
+IN: compiler.cfg
 
 HELP: basic-block
 { $class-description
   "Factors representation of a basic block in the cfg. A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching. It has the following slots:"
   { $table
     { { $slot "successors" } { "A " { $link vector } " of basic blocks that may be executed directly after this block. Most blocks only have one successor but a block that checks where an if-condition should branch to would have two for example." } }
-    { { $slot "word" } { "The " { $link word } " the cfg is produced of." } }
+    { { $slot "instructions" } { "A " { $link vector } " of " { $link insn } " tuples which form the instructions of the basic block." } }
   }
 } ;
 
@@ -18,6 +20,6 @@ HELP: cfg
   "Call flow graph. It has the following slots:"
   { $table
     { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } }
-    { { $slot "word" } { "The " { $link word } " the cfg is produced of." } }
+    { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
   }
 } ;

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

@@ -12,10 +12,6 @@ compiler.cfg.instructions
 compiler.cfg.predecessors ;
 IN: 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.
-
 <PRIVATE
 
 : insert-gc-check? ( bb -- ? )

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

@@ -1,6 +1,11 @@
 USING: help.markup help.syntax kernel layouts slots.private ;
 IN: compiler.cfg.instructions
 
+HELP: insn
+{ $class-description
+  "Base class for all virtual cpu instructions, used by the CFG IR."
+} ;
+
 HELP: vreg-insn
 { $class-description
   "Base class for instructions that uses vregs."

basis/compiler/cfg/instructions/instructions.factor

@@ -13,7 +13,6 @@ V{ } clone insn-classes set-global
 
 : new-insn ( ... class -- insn ) f swap boa ; inline
 
-! Virtual CPU instructions, used by CFG IR
 TUPLE: insn ;
 
 TUPLE: vreg-insn < insn ;

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

@@ -1,10 +1,13 @@
-USING: help.markup help.syntax literals multiline sequences ;
+USING: help.markup help.syntax literals multiline sequences splitting ;
 IN: compiler.cfg.instructions.syntax
 
 <<
-STRING: parse-insn-slot-specs-ex
+STRING: parse-insn-slot-specs-code
 USING: compiler.cfg.instructions.syntax prettyprint splitting ;
 "use: src/int-rep temp: temp/int-rep" " " split parse-insn-slot-specs .
+;
+
+STRING: parse-insn-slot-specs-result
 {
     T{ insn-slot-spec
         { type use }
@@ -26,4 +29,6 @@ HELP: parse-insn-slot-specs
   { "specs" "a " { $link sequence } " of " { $link insn-slot-spec } " items." }
 }
 { $description "Parses a sequence of tokens into a sequence of instruction slot specifiers." }
-{ $examples { $example $[ parse-insn-slot-specs-ex ] } } ;
+{ $examples
+  { $example $[ parse-insn-slot-specs-code parse-insn-slot-specs-result ] }
+} ;

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

@@ -8,7 +8,7 @@ HELP: emit-height-changes
 { $description "Emits stack height change instructions to the CFG being built." }
 { $examples
   { $example
-    "USING: compiler.cfg.stacks.local make prettyprint ;"
+    "USING: compiler.cfg.stacks.local make namespaces prettyprint ;"
     "T{ current-height { emit-d 4 } { emit-r -2 } } current-height set [ emit-height-changes ] { } make ."
     "{ T{ ##inc-d { n 4 } } T{ ##inc-r { n -2 } } }"
   }

basis/compiler/codegen/codegen-docs.factor

@@ -54,7 +54,7 @@ HELP: labels
 { $description { $link hashtable } " of mappings from " { $link basic-block } " to " { $link label } "." } ;
 
 HELP: lookup-label
-{ $values { "bb" basic-block } }
+{ $values { "bb" basic-block } { "label" label } }
 { $description "Sets and gets a " { $link label } " for the " { $link basic-block } ". The labels are used to generate branch instructions from one block to another." } ;
 
 HELP: generate-block

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

@@ -1,8 +1,9 @@
-USING: help.markup help.syntax ;
+USING: help.markup help.syntax sequences ;
 IN: compiler.tree.cleanup
 
 ARTICLE: "compiler.tree.cleanup" "Cleanup Phase"
 "A phase run after propagation to finish the job, so to speak. Codifies speculative inlining decisions, deletes branches marked as never taken, and flattens local recursive blocks that do not call themselves." ;
 
 HELP: cleanup
+{ $values { "nodes" sequence } { "nodes'" sequence } }
 { $description "Main entry point for the cleanup optimization phase." } ;

basis/compiler/tree/cleanup/cleanup.factor

@@ -12,11 +12,6 @@ compiler.tree.propagation.info
 compiler.tree.propagation.branches ;
 IN: compiler.tree.cleanup
 
-! A phase run after propagation to finish the job, so to speak.
-! Codifies speculative inlining decisions, deletes branches
-! marked as never taken, and flattens local recursive blocks
-! that do not call themselves.
-
 GENERIC: delete-node ( node -- )
 
 M: #call-recursive delete-node

basis/compiler/tree/propagation/known-words/known-words-docs.factor

@@ -7,7 +7,8 @@ HELP: binary-op-class
 { $description "Given two value infos return the math class which is large enough for both of them." }
 { $examples
   { $example
-    "USING: compiler.tree.propagation.known-words compiler.tree.propagation.info math prettyprint ;"
+    "USING: compiler.tree.propagation.known-words compiler.tree.propagation.info"
+    "kernel math prettyprint ;"
     "bignum real [ <class-info> ] bi@ binary-op-class ."
     "real"
   }
@@ -30,8 +31,8 @@ HELP: fits-in-fixnum?
 { $description "Checks if the interval is a subset of the " { $link fixnum } " interval. Used to see if arithmetic may overflow." }
 { $examples
   { $example
-    "USING: compiler.tree.propagation.known-words prettyprint ;"
-    "clear full-interval fits-in-fixnum? ."
+    "USING: compiler.tree.propagation.known-words math.intervals prettyprint ;"
+    "full-interval fits-in-fixnum? ."
     "f"
   }
 } ;

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

@@ -1,6 +1,7 @@
 USING: help.markup help.syntax literals multiline ;
 IN: compiler.tree.propagation
 
+<<
 STRING: propagate-ex
 USING: compiler.tree.builder compiler.tree.propagation math prettyprint ;
 [ 3 + ] build-tree propagate third .
@@ -42,6 +43,7 @@ T{ #call
     }
 }
 ;
+>>
 
 HELP: propagate
 { $values { "nodes" "a sequence of nodes" } }

basis/compiler/tree/propagation/propagation.factor

@@ -15,7 +15,7 @@ IN: compiler.tree.propagation
 
 ! This pass must run after normalization
 
-: propagate ( node -- node )
+: propagate ( nodes -- nodes )
     H{ } clone copies set
     H{ } clone 1array value-infos set
     H{ } clone 1array constraints set

basis/compiler/tree/tree-docs.factor

@@ -35,6 +35,15 @@ HELP: #shuffle
   }
 } ;
 
+HELP: #if
+{ $class-description "SSA tree node that implements conditional branching. It has the following slots:"
+  { $table
+    { { $slot "children" }
+      { "A two item " { $link sequence } ". The first item holds the instructions executed if the condition is true and the second those that are executed if it is not true." }
+    }
+  }
+} ;
+
 HELP: node,
 { $values { "node" node } }
 { $description "Emits a node to the " { $link stack-visitor } " variable." } ;

basis/cpu/x86/64/64-docs.factor

@@ -2,6 +2,7 @@ USING: help.markup help.syntax math ;
 IN: cpu.x86.64
 
 HELP: vm-reg
+{ $values { "reg" "a register symbol" } }
 { $description
   "Symbol of the machine register that holds the address of the virtual machine."
 } ;

basis/cpu/x86/x86-docs.factor

@@ -1,17 +1,20 @@
-USING: help.markup help.syntax ;
+USING: help.markup help.syntax math ;
 IN: cpu.x86
 
 HELP: stack-reg
+{ $values { "reg" "a register symbol" } }
 { $description
   "Symbol of the machine register that holds the (cpu) stack address."
 } ;
 
 HELP: ds-reg
+{ $values { "reg" "a register symbol" } }
 { $description
   "Symbol of the machine register that holds the address to the data stack's location."
 } ;
 
 HELP: (%inc)
+{ $values { "n" number } { "reg" "a register symbol" } }
 { $description
   "Emits machine code for increasing or decreasing the given register a number of cell sizes bytes."
 }

core/generic/math/math-docs.factor

@@ -3,7 +3,7 @@ sequences quotations generic.math.private ;
 IN: generic.math
 
 HELP: math-class-max
-{ $values { "class1" class } { "class2" class } }
+{ $values { "class1" class } { "class2" class } { "class" class } }
 { $description "Evaluates which math class is the largest." }
 { $examples
   { $example