From e968c16139c02a31e16021f97f82cc117635fe1a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Thu, 18 Dec 2014 17:12:41 +0100
Subject: [PATCH] compiler.cfg.stacks.finalize: initial docs

---
 .../cfg/stacks/finalize/finalize-docs.factor  | 28 +++++++++++++++++++
 .../cfg/stacks/finalize/finalize.factor       | 10 -------
 2 files changed, 28 insertions(+), 10 deletions(-)
 create mode 100644 basis/compiler/cfg/stacks/finalize/finalize-docs.factor

diff --git a/basis/compiler/cfg/stacks/finalize/finalize-docs.factor b/basis/compiler/cfg/stacks/finalize/finalize-docs.factor
new file mode 100644
index 0000000000..c0c1daf248
--- /dev/null
+++ b/basis/compiler/cfg/stacks/finalize/finalize-docs.factor
@@ -0,0 +1,28 @@
+USING: assocs compiler.cfg help.markup help.syntax ;
+IN: compiler.cfg.stacks.finalize
+
+HELP: inserting-peeks
+{ $values { "from" basic-block } { "to" basic-block } { "assoc" assoc } }
+{ $description
+  "A peek is inserted on an edge if the destination anticipates the stack location, the source does not anticipate it and it is not available from the source in a register." } ;
+
+HELP: inserting-replaces
+{ $values { "from" basic-block } { "to" basic-block } { "assoc" assoc } }
+{ $description
+  "A replace is inserted on an edge if two conditions hold:"
+  { $list
+    "the location is not dead at the destination, OR the location is live at the destination but not available at the destination."
+    "the location is pending in the source but not the destination"
+  }
+} ;
+
+{ inserting-replaces inserting-peeks } related-words
+
+HELP: finalize-stack-shuffling
+{ $values { "cfg" cfg } }
+{ $description "Called to end the stack analysis." } ;
+
+ARTICLE: "compiler.cfg.stacks.finalize" "Stack finalization"
+"This pass inserts peeks and replaces." ;
+
+ABOUT: "compiler.cfg.stacks.finalize"
diff --git a/basis/compiler/cfg/stacks/finalize/finalize.factor b/basis/compiler/cfg/stacks/finalize/finalize.factor
index 72276dd42d..02367e9baf 100644
--- a/basis/compiler/cfg/stacks/finalize/finalize.factor
+++ b/basis/compiler/cfg/stacks/finalize/finalize.factor
@@ -7,22 +7,12 @@ compiler.cfg.stacks.local compiler.cfg.utilities fry kernel
 locals make math sequences ;
 IN: compiler.cfg.stacks.finalize
 
-! This pass inserts peeks and replaces.
-
 :: inserting-peeks ( from to -- assoc )
-    ! A peek is inserted on an edge if the destination anticipates
-    ! the stack location, the source does not anticipate it and
-    ! it is not available from the source in a register.
     to anticip-in
     from anticip-out from avail-out assoc-union
     assoc-diff ;
 
 :: inserting-replaces ( from to -- assoc )
-    ! A replace is inserted on an edge if two conditions hold:
-    ! - the location is not dead at the destination, OR
-    !   the location is live at the destination but not available
-    !   at the destination
-    ! - the location is pending in the source but not the destination
     from pending-out to pending-in assoc-diff
     to dead-in to live-in to anticip-in assoc-diff assoc-diff
     assoc-diff ;