Docs: mostly fixes for doc errors found by help lint

diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor
index e6aca7990eed105b76816f34d30df4c78010000d..367dcf99ddc90221f069a0a7683c6cca048f4b40 100644 (file)
--- a/basis/compiler/cfg/cfg-docs.factor
+++ b/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." } }
   }
 } ;

diff --git a/basis/compiler/cfg/gc-checks/gc-checks.factor b/basis/compiler/cfg/gc-checks/gc-checks.factor
index c7f79b5ef561cf2ff214a7ce1c1a7fec8b7c1276..42b32dbb28345cd4c641af8aa810cd2ce63293ac 100644 (file)
--- a/basis/compiler/cfg/gc-checks/gc-checks.factor
+++ b/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 -- ? )

diff --git a/basis/compiler/cfg/instructions/instructions-doc.factor b/basis/compiler/cfg/instructions/instructions-doc.factor
index d4c4d8e3394028736ab1da3a2dc6df2864a13d66..20c6f4ceb7874a023fd612e92d74e75a795007aa 100644 (file)
--- a/basis/compiler/cfg/instructions/instructions-doc.factor
+++ b/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."

diff --git a/basis/compiler/cfg/instructions/instructions.factor b/basis/compiler/cfg/instructions/instructions.factor
index df6dcf9af3347ba6dfbf77eb14f2d89b2e00f6f9..2f1b2eaf6edc2293e1dff80cebe9f70433eb313e 100644 (file)
--- a/basis/compiler/cfg/instructions/instructions.factor
+++ b/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 ;

diff --git a/basis/compiler/cfg/instructions/syntax/syntax-docs.factor b/basis/compiler/cfg/instructions/syntax/syntax-docs.factor
index c24e43850fb9b5a2513e3d8b60747a1e4bc0e5da..856b927bb05518610d9a3929ed620ec3881b2da9 100644 (file)
--- a/basis/compiler/cfg/instructions/syntax/syntax-docs.factor
+++ b/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 ] }
+} ;

diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor
index 60b3c6a2dcce5219e9f991f4b78922130bc9e464..3550add1835b6d951830ad52a3223c82f54ed3c3 100644 (file)
--- a/basis/compiler/cfg/stacks/local/local-docs.factor
+++ b/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 } } }"
   }

diff --git a/basis/compiler/codegen/codegen-docs.factor b/basis/compiler/codegen/codegen-docs.factor
index 9c8c04e653fd5ef4416d60a2a6cc6dd0aaa92341..37ae572db07d6b03d65300433abf173d660de0f4 100644 (file)
--- a/basis/compiler/codegen/codegen-docs.factor
+++ b/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

diff --git a/basis/compiler/tree/cleanup/cleanup-docs.factor b/basis/compiler/tree/cleanup/cleanup-docs.factor
index 4f09dea269ed319f0c3b44b2502180ee8f9b92d6..73ca20baa231a1eb734a3a73d17e5885e266682d 100644 (file)
--- a/basis/compiler/tree/cleanup/cleanup-docs.factor
+++ b/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." } ;

diff --git a/basis/compiler/tree/cleanup/cleanup.factor b/basis/compiler/tree/cleanup/cleanup.factor
index 5cf2a4f46998ee470a4e644ce7fdb70f327eacb9..6c9d846da857a4367f52bd1b43eede2319449fb5 100644 (file)
--- a/basis/compiler/tree/cleanup/cleanup.factor
+++ b/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

diff --git a/basis/compiler/tree/propagation/known-words/known-words-docs.factor b/basis/compiler/tree/propagation/known-words/known-words-docs.factor
index b79f3314a9a28e4cf38167e1e3bd1d1535341e0d..ec49f2e24a391609464fcbf749a6657529d70432 100644 (file)
--- a/basis/compiler/tree/propagation/known-words/known-words-docs.factor
+++ b/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"
   }
 } ;

diff --git a/basis/compiler/tree/propagation/propagation-docs.factor b/basis/compiler/tree/propagation/propagation-docs.factor
index 9e7a689c5b031e7fad7d9c032c4f2da097a97cc1..039ea4469203a6744a93c8a7a1a4d238c70cfbaa 100644 (file)
--- a/basis/compiler/tree/propagation/propagation-docs.factor
+++ b/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" } }

diff --git a/basis/compiler/tree/propagation/propagation.factor b/basis/compiler/tree/propagation/propagation.factor
index a11264fb7ff9cf1bf64823c10a4e82227a15cb0d..81309088c490fae739b9d1d9ec7bf2c0e14926ac 100644 (file)
--- a/basis/compiler/tree/propagation/propagation.factor
+++ b/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

diff --git a/basis/compiler/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor
index 7b6e254fd79a0be41c0fcf96596b9079da90265b..ef98930318420e74db093eaf2033908eb76fbd1a 100644 (file)
--- a/basis/compiler/tree/tree-docs.factor
+++ b/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." } ;

diff --git a/basis/cpu/x86/64/64-docs.factor b/basis/cpu/x86/64/64-docs.factor
index e13bddf9b5d6ae8b4564292d1cade52f1fedf2ef..26fbfc1a196f387197254f5c4437a08f8e64e268 100644 (file)
--- a/basis/cpu/x86/64/64-docs.factor
+++ b/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."
 } ;

diff --git a/basis/cpu/x86/x86-docs.factor b/basis/cpu/x86/x86-docs.factor
index 611ceb3736e61513ee5a3943dbacc8894a5a049a..bc287595f3aa3d7e396bff22418b51f7ffd22a07 100644 (file)
--- a/basis/cpu/x86/x86-docs.factor
+++ b/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."
 }

diff --git a/core/generic/math/math-docs.factor b/core/generic/math/math-docs.factor
index f541db2486c8ed925added7143d6656ba2f64b8c..ce69b2999ff893ece5017461d77ca08a38dec1eb 100644 (file)
--- a/core/generic/math/math-docs.factor
+++ b/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