Docs: docs for compiler-related words

basis/compiler/cfg/cfg-docs.factor

@@ -1,5 +1,5 @@
-USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax
+USING: compiler.cfg compiler.cfg.instructions compiler.cfg.rpo help.markup
-namespaces vectors words ;
+help.syntax namespaces sequences vectors words ;
 IN: compiler.cfg
 
 HELP: basic-block
@@ -21,5 +21,11 @@ HELP: cfg
   { $table
     { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } }
     { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
+    { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
   }
-} ;
+}
+{ $see-also post-order } ;
+
+HELP: cfg-changed
+{ $values { "cfg" cfg } }
+{ $description "Resets all \"calculated\" slots in the cfg which forces them to be recalculated." } ;

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

@@ -1,6 +1,12 @@
 USING: compiler.cfg help.markup help.syntax kernel layouts slots.private ;
 IN: compiler.cfg.instructions
 
+HELP: new-insn
+{ $values { "class" class } { "insn" insn } }
+{ $description
+  "Boa wrapper for the " { $link insn } " class with " { $slot "insn#" } " set to " { $link f } "."
+} ;
+
 HELP: insn
 { $class-description
   "Base class for all virtual cpu instructions, used by the CFG IR."
@@ -21,7 +27,7 @@ HELP: foldable-insn
 
 HELP: ##inc-d
 { $class-description
-  "An instruction that increases or decreases the data stacks size by n. For example, " { $link 2drop } " decreases it by two and pushing an item increases it by one."
+  "An instruction that increases or decreases the data stacks height by n. For example, " { $link 2drop } " decreases it by two and pushing an item increases it by one."
 } ;
 
 HELP: ##prologue

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

@@ -0,0 +1,11 @@
+USING: compiler.cfg compiler.cfg.linearization compiler.codegen help.markup
+help.syntax kernel macros sequences ;
+IN: compiler.cfg.linearization
+
+HELP: linearization-order
+{ $values
+  { "cfg" cfg }
+  { "bb" sequence }
+}
+{ $description "Lists the basic blocks in linearization order. That is, the order in which they will be written in the generated assembly code." }
+{ $see-also generate } ;

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

@@ -16,7 +16,7 @@ HELP: translate-local-loc
 } ;
 
 HELP: emit-height-changes
-{ $description "Emits stack height change instructions to the CFG being built." }
+{ $description "Emits stack height change instructions to the CFG being built. This is done when a " { $link basic-block } " is begun or ended." }
 { $examples
   { $example
     "USING: compiler.cfg.stacks.local make namespaces prettyprint ;"

basis/compiler/codegen/codegen-docs.factor

@@ -65,11 +65,10 @@ HELP: generate
 { $values { "cfg" cfg } { "code" sequence } }
 { $description "Generates assembly code for the given cfg. The output " { $link sequence } " has six items with the following interpretations:"
   { $list
-    { "The first element is a sequence of alien function symbols and " { $link dll } "s used by the cfg interleaved." }
+    { "The first element is a sequence of alien function symbols and " { $link dll } "s used by the cfg interleaved. That is, the " { $link parameter-table } "." }
-    "The second item is the parameter table."
+    { "The second item is the " { $link literal-table } "." }
-    { "The third item is the " { $link literal-table } "." }
     { "The third item is the relocation table as a " { $link byte-array } "." }
-    "The fourth item is the label table."
+    { "The fourth item is the " { $link label-table } "." }
     { "The fifth item is the generated assembly code as a " { $link byte-array } ". It still contains unresolved crossreferences." }
     "The sixth item is the size of the stack frame in bytes."
   }

basis/compiler/compiler-docs.factor

@@ -1,4 +1,4 @@
-USING: assocs compiler.cfg.builder compiler.cfg.optimizer
+USING: assocs compiler.cfg compiler.cfg.builder compiler.cfg.optimizer
 compiler.errors compiler.tree.builder compiler.tree.optimizer
 compiler.units compiler.codegen help.markup help.syntax io
 parser quotations sequences words ;
@@ -58,6 +58,11 @@ HELP: frontend
 { $values { "word" word } { "tree" sequence } }
 { $description "First step of the compilation process. It outputs a high-level tree in SSA form." } ;
 
+HELP: backend
+{ $values { "tree" "a " { $link sequence } " of SSA nodes" } { "word" word } }
+{ $description "The second last step of the compilation process. A word and its SSA tree is taken as input and a " { $link cfg } " is built from which assembly code is generated." }
+{ $see-also generate } ;
+
 HELP: compile-word
 { $values { "word" word } }
 { $description "Compile a single word." }

basis/cpu/x86/assembler/operands/operands-docs.factor

@@ -0,0 +1,6 @@
+USING: cpu.x86.assembler.operands.private help.markup help.syntax math ;
+IN: cpu.x86.assembler.operands
+
+HELP: [RIP+]
+{ $values { "displacement" number } { "indirect" indirect } }
+{ $description "Creates an indirect operand relative to the RIP register." } ;

core/compiler/units/units-docs.factor

@@ -85,7 +85,7 @@ $nl
 "The alist maps words to one of the following:"
 { $list
     { "a quotation - in this case, the quotation is compiled with the non-optimizing compiler and the word will call the quotation when executed." }
-    { "a 5-element array " { $snippet "{ parameters literals relocation labels code }" } " - in this case, a code heap block is allocated with the given data and the word will call the code block when executed. This is used by the optimizing compiler." }
+    { "a 6-element array " { $snippet "{ parameters literals relocation labels code stack-frame-size }" } " - in this case, a code heap block is allocated with the given data and the word will call the code block when executed. This is used by the optimizing compiler." }
 }
 "If any of the redefined words may already be referenced by other words in the code heap, from outside of the compilation unit, then a scan of the code heap must be performed to update all word call sites. Passing " { $link t } " as the " { $snippet "update-existing?" } " parameter enables this code path."
 $nl

core/words/words-docs.factor

@@ -345,6 +345,11 @@ HELP: deprecated?
 { $description "Tests if an object is " { $link POSTPONE: deprecated } "." }
 { $notes "Outputs " { $link f } " if the object is not a word." } ;
 
+HELP: inline?
+{ $values { "obj" object } { "?" "a boolean" } }
+{ $description "Tests if an object is " { $link POSTPONE: inline } "." }
+{ $notes "Outputs " { $link f } " if the object is not a word." } ;
+
 HELP: subwords
 { $values { "word" word } { "seq" sequence } }
 { $description "Lists all specializations for the given word." }