From: Matt S Trout <mst@shadowcat.co.uk>
Date: Tue, 26 Jun 2012 19:27:47 +0000 (+0000)
Subject: extra quote_sub docs from kentnl
X-Git-Tag: v0.091010~3
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9c8204612cac46da05778bf98efa6b45ae91c62b;p=gitmo%2FMoo.git

extra quote_sub docs from kentnl
---

diff --git a/Changes b/Changes
index e9a1532..0a15a5f 100644
--- a/Changes
+++ b/Changes
@@ -1,3 +1,4 @@
+  - additional quote_sub docs
   - remove multi-populate code to fix exists/defined new() bug
   - document move to #moose and include repository metadata
   - no Moo and no Moo::Role
diff --git a/lib/Sub/Quote.pm b/lib/Sub/Quote.pm
index 8567d78..d067e2a 100644
--- a/lib/Sub/Quote.pm
+++ b/lib/Sub/Quote.pm
@@ -220,3 +220,34 @@ arguments.
 Generates a snippet of code which is suitable to be used as a prelude for
 L</inlinify>.  The keys are the names of the variables and the values are (duh)
 the values.  Note that references work as values.
+
+=head1 CAVEATS
+
+Much of this is just string-based code-generation, and as a result, a few caveats
+apply.
+
+=head2 return
+
+Calling C<return> from a quote_sub'ed sub will not likely do what you intend.
+Instead of returning from the code you defined in C<quote_sub>, it will return
+from the overall function it is composited into.
+
+So when you pass in:
+
+   quote_sub q{  return 1 if $condition; $morecode }
+
+It might turn up in the intended context as follows:
+
+  sub foo {
+
+    <important code a>
+    do {
+      return 1 if $condition;
+      $morecode
+    };
+    <important code b>
+
+  }
+
+Which will obviously return from foo, when all you meant to do was return from
+the code context in quote_sub and proceed with running important code b.