--- JSON-XS/XS.pm	2007/03/25 21:19:13	1.23
+++ JSON-XS/XS.pm	2007/03/29 01:27:36	1.24
@@ -286,16 +286,21 @@
 =item $json = $json->shrink ([$enable])
 
 Perl usually over-allocates memory a bit when allocating space for
-strings.  This flag optionally resizes strings generated by either
+strings. This flag optionally resizes strings generated by either
 C<encode> or C<decode> to their minimum size possible. This can save
 memory when your JSON texts are either very very long or you have many
 short strings. It will also try to downgrade any strings to octet-form
 if possible: perl stores strings internally either in an encoding called
 UTF-X or in octet-form. The latter cannot store everything but uses less
-space in general.
+space in general (and some buggy Perl or C code might even rely on that
+internal representation being used).
 
-If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
-while all strings generated by C<decode> will also be shrunk-to-fit.
+The actual definition of what shrink does might change in future versions,
+but it will always try to save space at the expense of time.
+
+If C<$enable> is true (or missing), the string returned by C<encode> will
+be shrunk-to-fit, while all strings generated by C<decode> will also be
+shrunk-to-fit.
 
 If C<$enable> is false, then the normal perl allocation algorithms are used.
 If you work with your data, then this is likely to be faster.