compiler.cfg.*: a little more docs

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

@@ -1,6 +1,11 @@
-USING: compiler.cfg help.markup help.syntax ;
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax ;
 IN: compiler.cfg.block-joining
 
 HELP: join-block?
 { $values { "bb" basic-block } { "?" "a boolean" } }
 { $description "Whether the block can be joined with its predecessor or not." } ;
+
+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." ;
+
+ABOUT: "compiler.cfg.block-joining"

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

@@ -5,9 +5,6 @@ compiler.cfg compiler.cfg.predecessors compiler.cfg.rpo
 compiler.cfg.utilities kernel sequences ;
 IN: compiler.cfg.block-joining
 
-! Joining blocks that are not calls and are connected by a single CFG edge.
-! This pass does not update ##phi nodes and should therefore only run
-! before stack analysis.
 : join-block? ( bb -- ? )
     {
         [ kill-block?>> not ]

basis/compiler/cfg/builder/builder.factor

@@ -95,7 +95,7 @@ M: #recursive emit-node
     dup label>> loop?>> [ emit-loop ] [ emit-recursive ] if ;
 
 ! #if
-: emit-branch ( obj -- final-bb )
+: emit-branch ( obj -- pair/f )
     [ emit-nodes ] with-branch ;
 
 : emit-if ( node -- )

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

@@ -2,7 +2,7 @@ USING: compiler.cfg.instructions help.markup help.syntax ;
 IN: compiler.cfg.representations.peephole
 
 HELP: convert-to-zero-vector?
-{ $values { "insn" insn } }
+{ $values { "insn" insn } { "?" "a boolean" } }
 { $description "When a literal zeroes/ones vector is unboxed, we replace the " { $link ##load-reference } " with a " { $link ##zero-vector } " or " { $link ##fill-vector } " instruction since this is more efficient." } ;
 
 

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

@@ -18,7 +18,7 @@ HELP: fill-gc-maps
 { $description "Populates the scrub-d, check-d, scrub-r and check-r slots of all gc maps in the cfg." } ;
 
 HELP: state>gc-data
-{ $values { "state" } { "gc-data" } }
+{ $values { "state" sequence } { "gc-data" sequence } }
 { $description "Takes a stack state on the format given by " { $link trace-stack-state } " and emits an array containing two bit-patterns with locations on the data and retain stacks to scrub." } ;
 
 HELP: vacant>bits

basis/compiler/codegen/relocation/relocation-docs.factor

@@ -40,3 +40,8 @@ HELP: compiled-offset
     "t\nt"
   }
 } ;
+
+ARTICLE: "compiler.codegen.relocation" "Relocatable VM objects"
+"The " { $vocab-link "compiler.codegen.relocation" } " deals with assigning memory addresses to VM objects, such as the card table. Those objects have different addresses during each execution which is why they are \"relocatable\". The vocab is shared by the optimizing and non-optimizing compiler." ;
+
+ABOUT: "compiler.codegen.relocation"

basis/compiler/codegen/relocation/relocation.factor

@@ -5,12 +5,6 @@ compiler.constants kernel make math math.bitwise memoize
 namespaces sequences ;
 IN: compiler.codegen.relocation
 
-! Common code shared by optimizing and non-optimizing compilers.
-! Should not have too many dependencies on the rest of the
-! optimizing compiler.
-
-! Code is compiled into the 'make' vector.
-
 SYMBOL: extra-offset  ! Only used by non-optimizing compiler
 
 : compiled-offset ( -- n )
@@ -35,7 +29,6 @@ SYMBOL: literal-table
 
 : add-literal ( obj -- ) literal-table get push ;
 
-! Relocation table
 SYMBOL: relocation-table
 
 : push-uint ( value vector -- )

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

@@ -23,7 +23,7 @@ HELP: call-effect-unsafe?
 { $description "Checks if the given effect is safe with regards to the cached one." } ;
 
 HELP: update-inline-cache
-{ $values { "word/quot" } { "ic" inline-cache } }
+{ $values { "word/quot" "word or quotation" } { "ic" inline-cache } }
 { $description "Sets the inline caches " { $slot "value" } " to the given word/quot and updates its " { $slot "counter" } " to the value of the " { $link effect-counter } "." } ;