From 0bb3e2397ba84cdef755f2f336196f82dd7b8271 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Tue, 6 May 2014 18:09:34 +0200
Subject: [PATCH] Docs: more compiler documentation

---
 basis/compiler/cfg/cfg-docs.factor                |  7 +++++--
 .../cfg/instructions/instructions-doc.factor      |  5 +++++
 basis/compiler/cfg/stacks/local/local-docs.factor | 15 +++++++++++++++
 basis/compiler/tree/tree-docs.factor              |  9 ++++++++-
 4 files changed, 33 insertions(+), 3 deletions(-)
 create mode 100644 basis/compiler/cfg/stacks/local/local-docs.factor

diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor
index bda3118f28..01161043ac 100644
--- a/basis/compiler/cfg/cfg-docs.factor
+++ b/basis/compiler/cfg/cfg-docs.factor
@@ -1,8 +1,11 @@
-USING: compiler.cfg help.markup help.syntax ;
+USING: compiler.cfg help.markup help.syntax vectors ;
 
 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."
+  "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." } }
+  }
 } ;
 
 HELP: <basic-block>
diff --git a/basis/compiler/cfg/instructions/instructions-doc.factor b/basis/compiler/cfg/instructions/instructions-doc.factor
index 962dfb9767..ba54bf4c3b 100644
--- a/basis/compiler/cfg/instructions/instructions-doc.factor
+++ b/basis/compiler/cfg/instructions/instructions-doc.factor
@@ -11,6 +11,11 @@ HELP: ##inc-d
   "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."
 } ;
 
+HELP: ##alien-invoke
+{ $class-description
+  "An instruction for calling a function in a dynamically linked library."
+} ;
+
 HELP: ##set-slot
 { $class-description
   "An instruction for non-primitive non-immediate variant of " { $link set-slot } ". It has the following slots:"
diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor
new file mode 100644
index 0000000000..60b3c6a2dc
--- /dev/null
+++ b/basis/compiler/cfg/stacks/local/local-docs.factor
@@ -0,0 +1,15 @@
+USING: compiler.cfg help.markup help.syntax ;
+IN: compiler.cfg.stacks.local
+
+HELP: current-height
+{ $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } "." } ;
+
+HELP: emit-height-changes
+{ $description "Emits stack height change instructions to the CFG being built." }
+{ $examples
+  { $example
+    "USING: compiler.cfg.stacks.local make 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/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor
index 70eb40bbfc..7c8d89473f 100644
--- a/basis/compiler/tree/tree-docs.factor
+++ b/basis/compiler/tree/tree-docs.factor
@@ -1,6 +1,13 @@
-USING: assocs help.markup help.syntax kernel sequences stack-checker.visitor ;
+USING: assocs help.markup help.syntax kernel sequences stack-checker.alien
+stack-checker.visitor ;
 IN: compiler.tree
 
+HELP: #alien-node
+{ $class-description "Base class for alien nodes. Its " { $snippet "params" } " slot holds an instance of the " { $link alien-node-params } " class." } ;
+
+HELP: #alien-invoke
+{ $class-description "SSA tree node that calls a function in a dynamically linked library." } ;
+
 HELP: #call
 { $class-description "SSA tree node that calls a word." } ;