--- CBOR-XS/XS.pm	2013/10/27 20:40:25	1.6
+++ CBOR-XS/XS.pm	2013/10/27 22:35:15	1.7
@@ -223,16 +223,9 @@
 
 =item CBOR tag 256 (perl object)
 
-The tag value C<256> (TODO: pending iana registration) will be used to
-deserialise a Perl object.
-
-TODO For this to work, the class must be loaded and must have a
-C<FROM_CBOR> method. The decoder will then call the C<FROM_CBOR> method
-with the constructor arguments provided by the C<TO_CBOR> method (see
-below).
-
-The C<FROM_CBOR> method must return a single value that will then be used
-as the deserialised value.
+The tag value C<256> (TODO: pending iana registration) will be used
+to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT
+SERIALISATION", below, for details.
 
 =item CBOR tag 55799 (magic header)
 
@@ -294,11 +287,10 @@
 values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
 if you want.
 
-=item blessed objects
+=item other blessed objects
 
-Other blessed objects currently need to have a C<TO_CBOR> method. It
-will be called on every object that is being serialised, and must return
-something that can be encoded in CBOR.
+Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
+"OBJECT SERIALISATION", below, for details.
 
 =item simple scalars
 
@@ -346,8 +338,105 @@
 
 =back
 
+=head2 OBJECT SERIALISATION
+
+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
+directly (most of them), it will first look up the C<TO_CBOR> method on
+it.
+
+If it has a C<TO_CBOR> method, it will call it with the object as only
+argument, and expects exactly one return value, which it will then
+substitute and encode it in the place of the object.
+
+Otherwise, it will look up the C<FREEZE> method. If it exists, it will
+call it with the object as first argument, and the constant string C<CBOR>
+as the second argument, to distinguish it from other serialisers.
+
+The C<FREEZE> method can return any number of values (i.e. zero or
+more). These will be encoded as CBOR perl object, together with the
+classname.
+
+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:
+
+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
+if the method cannot be found.
+
+After the lookup it will call the C<THAW> method with the stored classname
+as first argument, the constant string C<CBOR> as second argument, and all
+values returned by C<FREEZE> as remaining arguments.
+
+=head4 EXAMPLES
+
+Here is an example C<TO_CBOR> method:
+
+   sub My::Object::TO_CBOR {
+      my ($obj) = @_;
+
+      ["this is a serialised My::Object object", $obj->{id}]
+   }
+
+When a C<My::Object> is encoded to CBOR, it will instead encode a simple
+array with two members: a string, and the "object id". Decoding this CBOR
+string will yield a normal perl array reference in place of the object.
+
+A more useful and practical example would be a serialisation method for
+the URI module. CBOR has a custom tag value for URIs, namely 32:
+
+  sub URI::TO_CBOR {
+     my ($self) = @_;
+     my $uri = "$self"; # stringify uri
+     utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
+     CBOR::XS::tagged 32, "$_[0]"
+  }
+
+This will encode URIs as a UTF-8 string with tag 32, which indicates an
+URI.
+
+Decoding such an URI will not (currently) give you an URI object, but
+instead a CBOR::XS::Tagged object with tag number 32 and the string -
+exactly what was returned by C<TO_CBOR>.
+
+To serialise an object so it can automatically be deserialised, you need
+to use C<FREEZE> and C<THAW>. To take the URI module as example, this
+would be a possible implementation:
+
+   sub URI::FREEZE {
+      my ($self, $serialiser) = @_;
+      "$self" # encode url string
+   }
+
+   sub URI::THAW {
+      my ($class, $serialiser, $uri) = @_;
+
+      $class->new ($uri)
+   }
+
+Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
+example, a C<FREEZE> method that returns "type", "id" and "variant" values
+would cause an invocation of C<THAW> with 5 arguments:
+
+   sub My::Object::FREEZE {
+      my ($self, $serialiser) = @_;
+
+      ($self->{type}, $self->{id}, $self->{variant})
+   }
+
+   sub My::Object::THAW {
+      my ($class, $serialiser, $type, $id, $variant) = @_;
+
+      $class-<new (type => $type, id => $id, variant => $variant)
+   }
+
 
-=head2 MAGIC HEADER
+=head1 MAGIC HEADER
 
 There is no way to distinguish CBOR from other formats
 programmatically. To make it easier to distinguish CBOR from other
@@ -360,7 +449,7 @@
 required.
 
 
-=head2 CBOR and JSON
+=head1 CBOR and JSON
 
 CBOR is supposed to implement a superset of the JSON data model, and is,
 with some coercion, able to represent all JSON texts (something that other