prevent toke_scan_str moving backward in linestr

[p5sagit/Devel-Declare.git] / lib / Devel / Declare.pm

diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm
index 553065c..ed29686 100644 (file)
--- a/lib/Devel/Declare.pm
+++ b/lib/Devel/Declare.pm
@@ -513,8 +513,21 @@ things like C<q(this is a quote)>).
 
 Also it Does The Right Thing with nested delimiters (like C<q(this (is (a) quote))>).
 
-It returns the length of the expression matched.  Use C<get_lex_stuff> to
-get the actual matched text.
+It returns the effective length of the expression matched.  Really, what
+it returns is the difference in position between where the string started,
+within the buffer, and where it finished.  If the string extended across
+multiple lines then the contents of the buffer may have been completely
+replaced by the new lines, so this position difference is not the same
+thing as the actual length of the expression matched.  However, because
+moving backward in the buffer causes problems, the function arranges
+for the effective length to always be positive, padding the start of
+the buffer if necessary.
+
+Use C<get_lex_stuff> to get the actual matched text, the content of
+the string.  Because of the behaviour around multiline strings, you
+can't reliably get this from the buffer.  In fact, after the function
+returns, you can't rely on any content of the buffer preceding the end
+of the string.
 
 =head4 C<get_lex_stuff>