--- CBOR-XS/XS.pm	2013/11/20 01:09:46	1.19
+++ CBOR-XS/XS.pm	2013/11/20 02:03:08	1.20
@@ -173,14 +173,14 @@
 This option does not affect C<decode> in any way, and it is recommended to
 leave it off unless you know your communications partner.
 
-=item $cbor = $cbor->allow_sharable ([$enable])
+=item $cbor = $cbor->allow_sharing ([$enable])
 
-=item $enabled = $cbor->get_allow_sharable
+=item $enabled = $cbor->get_allow_sharing
 
 If C<$enable> is true (or missing), then C<encode> will not double-encode
-values that have been seen before (e.g. when the same object, such as an
-array, is referenced multiple times), but instead will emit a reference to
-the earlier value.
+values that have been referenced before (e.g. when the same object, such
+as an array, is referenced multiple times), but instead will emit a
+reference to the earlier value.
 
 This means that such values will only be encoded once, and will not result
 in a deep cloning of the value on decode, in decoders supporting the value
@@ -191,12 +191,11 @@
 increase the encoded size, as potentially shared values are encode as
 sharable whether or not they are actually shared.
 
-At the moment, all shared values will be detected, even weird and unusual
-cases, such as an array with multiple "copies" of the I<same> scalar,
-which are hard but not impossible to create in Perl (L<Storable> for
-example doesn't handle these cases). If this turns out ot be a performance
-issue then future versions might limit the shared value detection to
-references only.
+At the moment, only targets of references can be shared (e.g. scalars,
+arrays or hashes pointed to by a reference). Weirder constructs, such as
+an array with multiple "copies" of the I<same> string, which are hard but
+not impossible to create in Perl, are not supported (this is the same as
+for L<Storable>).
 
 If C<$enable> is false (the default), then C<encode> will encode
 exception when it encounters anything it cannot encode as CBOR.