--- Types-Serialiser/Serialiser.pm	2013/10/27 20:01:08	1.2
+++ Types-Serialiser/Serialiser.pm	2013/10/27 22:46:21	1.3
@@ -141,6 +141,60 @@
 While it is possible to use an isa test, directly comparing stash pointers
 is faster and guaranteed to work.
 
+=head1 A GENERIC OBJECT SERIALIATION PROTOCOL
+
+This section explains the object serialisation protocol used by
+L<CBOR::XS>. It is meant to be generic enough to support any kind of
+generic object serialiser.
+
+This protocol is called "the Types::Serialiser object serialisation
+protocol".
+
+=head2 ENCODING
+
+When the encoder encounters an object that it cannot otherwise encode (for
+example, L<CBOR::XS> can encode a few special types itself, and will first
+attempt to use the special C<TO_CBOR> serialisation protocol), it will
+look up the C<FREEZE> method on the object.
+
+If it exists, it will call it with two arguments: the object to
+serialise, and a constant string that indicates the name of the
+serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and
+L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second
+argument.
+
+The C<FREEZE> method can then return zero or more values to identify the
+object instance. The serialiser is then supposed to encode the class name
+and all of these return values (which must be encodable in the format)
+using the relevant form for perl objects. In CBOR for example, there is a
+registered tag number for encoded perl objects.
+
+=head2 DECODING
+
+When the decoder then encounters such an encoded perl object, it should
+look up the C<THAW> method on the stored classname, and invoke it with the
+classname, the constant string to identify the format, and all the return
+values returned by C<FREEZE>.
+
+=head2 EXAMPLES
+
+See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
+more details, an example implementation, and code examples.
+
+Here is an example C<FREEZE>/C<THAW> method pair:
+
+   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)
+   }
+
 =head1 BUGS
 
 The use of L<overload> makes this module much heavier than it should be