--- CBOR-XS/XS.pm	2013/11/30 16:19:59	1.30
+++ CBOR-XS/XS.pm	2013/11/30 18:13:53	1.31
@@ -50,9 +50,9 @@
 L<Storable>.
 
 In addition to the core CBOR data format, this module implements a
-number of extensions, to support cyclic and shared data structures (see
-C<allow_sharing>), string deduplication (see C<pack_strings>) and scalar
-references (always enabled).
+number of extensions, to support cyclic and shared data structures
+(see C<allow_sharing> and C<allow_cycles>), string deduplication (see
+C<pack_strings>) and scalar references (always enabled).
 
 The primary goal of this module is to be I<correct> and the secondary goal
 is to be I<fast>. To reach the latter goal it was written in C.
@@ -182,7 +182,8 @@
 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
 sharing extension. This also makes it possible to encode cyclic data
-structures.
+structures (which need C<allow_cycles> to ne enabled to be decoded by this
+module).
 
 It is recommended to leave it off unless you know your
 communication partner supports the value sharing extensions to CBOR
@@ -192,7 +193,7 @@
 Detecting shared values incurs a runtime overhead when values are encoded
 that have a reference counter large than one, and might unnecessarily
 increase the encoded size, as potentially shared values are encode as
-sharable whether or not they are actually shared.
+shareable whether or not they are actually shared.
 
 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
@@ -207,6 +208,21 @@
 This option does not affect C<decode> in any way - shared values and
 references will always be decoded properly if present.
 
+=item $cbor = $cbor->allow_cycles ([$enable])
+
+=item $enabled = $cbor->get_allow_cycles
+
+If C<$enable> is true (or missing), then C<decode> will happily decode
+self-referential (cyclic) data structures. By default these will not be
+decoded, as they need manual cleanup to avoid memory leaks, so code that
+isn't prepared for this will not leak memory.
+
+If C<$enable> is false (the default), then C<decode> will throw an error
+when it encounters a self-referential/cyclic data structure.
+
+This option does not affect C<encode> in any way - shared values and
+references will always be decoded properly if present.
+
 =item $cbor = $cbor->pack_strings ([$enable])
 
 =item $enabled = $cbor->get_pack_strings
@@ -706,11 +722,25 @@
 objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
 serialisation protocol). See L<OBJECT SERIALISATION> for details.
 
-=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
+=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
 
-These tags are automatically decoded when encountered, resulting in
+These tags are automatically decoded when encountered (and they do not
+result in a cyclic data structure, see C<allow_cycles>), resulting in
 shared values in the decoded object. They are only encoded, however, when
-C<allow_sharable> is enabled.
+C<allow_sharing> is enabled.
+
+Not all shared values can be successfully decoded: values that reference
+themselves will I<currently> decode as C<undef> (this is not the same
+as a reference pointing to itself, which will be represented as a value
+that contains an indirect reference to itself - these will be decoded
+properly).
+
+Note that considerably more shared value data structures can be decoded
+than will be encoded - currently, only values pointed to by references
+will be shared, others will not. While non-reference shared values can be
+generated in Perl with some effort, they were considered too unimportant
+to be supported in the encoder. The decoder, however, will decode these
+values as shared values.
 
 =item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)