--- CBOR-XS/XS.pm	2013/11/28 16:09:04	1.28
+++ CBOR-XS/XS.pm	2013/11/30 15:23:59	1.29
@@ -467,10 +467,16 @@
 
 =head2 OBJECT SERIALISATION
 
+This module implements both a CBOR-specific and the generic
+L<Types::Serialier> object serialisation protocol. The following
+subsections explain both methods.
+
+=head3 ENCODING
+
 This module knows two way to serialise a Perl object: The CBOR-specific
 way, and the generic way.
 
-Whenever the encoder encounters a Perl object that it cnanot serialise
+Whenever the encoder encounters a Perl object that it cannot serialise
 directly (most of them), it will first look up the C<TO_CBOR> method on
 it.
 
@@ -486,11 +492,18 @@
 more). These will be encoded as CBOR perl object, together with the
 classname.
 
+These methods I<MUST NOT> change the data structure that is being
+serialised. Failure to comply to this can result in memory corruption -
+and worse.
+
 If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
 with an error.
 
-Objects encoded via C<TO_CBOR> cannot be automatically decoded, but
-objects encoded via C<FREEZE> can be decoded using the following protocol:
+=head3 DECODING
+
+Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded,
+but objects encoded via C<FREEZE> can be decoded using the following
+protocol:
 
 When an encoded CBOR perl object is encountered by the decoder, it will
 look up the C<THAW> method, by using the stored classname, and will fail
@@ -500,7 +513,7 @@
 as first argument, the constant string C<CBOR> as second argument, and all
 values returned by C<FREEZE> as remaining arguments.
 
-=head4 EXAMPLES
+=head3 EXAMPLES
 
 Here is an example C<TO_CBOR> method: