From 6a77bf8e69142b104ad2bb7fa1f5da88f7158f43 Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Thu, 17 Sep 2009 13:27:15 -0700
Subject: [PATCH] stack-checker.errors: improve documentation a bit

---
 basis/stack-checker/errors/errors-docs.factor | 38 +++++++++++++++++--
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/basis/stack-checker/errors/errors-docs.factor b/basis/stack-checker/errors/errors-docs.factor
index 6a67b815cd..e451c53c71 100755
--- a/basis/stack-checker/errors/errors-docs.factor
+++ b/basis/stack-checker/errors/errors-docs.factor
@@ -1,14 +1,43 @@
 USING: help.markup help.syntax kernel effects sequences
-sequences.private words ;
+sequences.private words combinators ;
 IN: stack-checker.errors
 
+HELP: do-not-compile
+{ $error-description "Thrown when inference encounters a macro being applied to a value which is not known to be a literal. Such code needs changes before it can compile and run. See " { $link "inference-combinators" } " and " { $link "inference-escape" } " for details." }
+{ $examples
+    "In this example, " { $link cleave } " is being applied to an array that is constructed on the fly. This is not allowed and fails to compile with a " { $link do-not-compile } " error:"
+    { $code
+        ": cannot-compile-call-example ( x -- y z )"
+        "    [ 1 + ] [ 1 - ] 2array cleave ;"
+    }
+} ;
+
 HELP: literal-expected
 { $error-description "Thrown when inference encounters a combinator or macro being applied to a value which is not known to be a literal, or constructed in a manner which can be analyzed statically. Such code needs changes before it can compile and run. See " { $link "inference-combinators" } " and " { $link "inference-escape" } " for details." }
 { $examples
-    "In this example, words calling " { $snippet "literal-expected-example" } " will have a static stac keffect, even if " { $snippet "literal-expected-example" } " does not:"
+    "In this example, the words being defined cannot be called, because they fail to compile with a " { $link literal-expected } " error:"
     { $code
-        ": literal-expected-example ( quot -- )"
+        ": bad-example ( quot -- )"
+        "    [ call ] [ call ] bi ;"
+        ""
+        ": usage ( -- )"
+        "    10 [ 2 * ] bad-example . ;"
+    }
+    "One fix is to declare the combinator as inline:"
+    { $code
+        ": good-example ( quot -- )"
         "    [ call ] [ call ] bi ; inline"
+        ""
+        ": usage ( -- )"
+        "    10 [ 2 * ] good-example . ;"
+    }
+    "Another fix is to use " { $link POSTPONE: call( } ":"
+    { $code
+        ": good-example ( quot -- )"
+        "    [ call( x -- y ) ] [ call( x -- y ) ] bi ;"
+        ""
+        ": usage ( -- )"
+        "    10 [ 2 * ] good-example . ;"
     }
 } ;
 
@@ -89,7 +118,8 @@ ARTICLE: "inference-errors" "Stack checker errors"
     { { $link "tools.inference" } " throws them as errors" }
     { "The " { $link "compiler" } " reports them via " { $link "tools.errors" } }
 }
-"Error thrown when insufficient information is available to calculate the stack effect of a combinator call (see " { $link "inference-combinators" } "):"
+"Errors thrown when insufficient information is available to calculate the stack effect of a call to a combinator or macro (see " { $link "inference-combinators" } "):"
+{ $subsection do-not-compile }
 { $subsection literal-expected }
 "Error thrown when a word's stack effect declaration does not match the composition of the stack effects of its factors:"
 { $subsection effect-error }