--- CBOR-XS/XS.pm	2013/10/29 00:20:26	1.11
+++ CBOR-XS/XS.pm	2013/10/29 15:13:50	1.12
@@ -456,6 +456,68 @@
 required.
 
 
+=head1 THE CBOR::XS::Tagged CLASS
+
+CBOR has the concept of tagged values - any CBOR value can be tagged with
+a numeric 64 bit number, which are centrally administered.
+
+C<CBOR::XS> handles a few tags internally when en- or decoding. You can
+also create tags yourself by encoding C<CBOR::XS::Tagged> objects, and the
+decoder will create C<CBOR::XS::Tagged> objects itself when it hits an
+unknown tag.
+
+These objects are simply blessed array references - the first member of
+the array being the numerical tag, the second being the value.
+
+You can interact with C<CBOR::XS::Tagged> objects in the following ways:
+
+=over 4
+
+=item $tagged = CBOR::XS::tag $tag, $value
+
+This function(!) creates a new C<CBOR::XS::Tagged> object using the given
+C<$tag> (0..2**64-1) to tag the given C<$value> (which can be any Perl
+value that can be encoded in CBOR, including serialisable Perl objects and
+C<CBOR::XS::Tagged> objects).
+
+=item $tagged->[0]
+
+=item $tagged->[0] = $new_tag
+
+=item $tag = $tagged->tag
+
+=item $new_tag = $tagged->tag ($new_tag)
+
+Access/mutate the tag.
+
+=item $tagged->[1]
+
+=item $tagged->[1] = $new_value
+
+=item $value = $tagged->value
+
+=item $new_value = $tagged->value ($new_value)
+
+Access/mutate the tagged value.
+
+=back
+
+=cut
+
+sub tag($$) {
+   bless [@_], CBOR::XS::Tagged::;
+}
+
+sub CBOR::XS::Tagged::tag {
+   $_[0][0] = $_[1] if $#_;
+   $_[0][0]
+}
+
+sub CBOR::XS::Tagged::value {
+   $_[0][1] = $_[1] if $#_;
+   $_[0][1]
+}
+
 =head1 CBOR and JSON
 
 CBOR is supposed to implement a superset of the JSON data model, and is,