--- CBOR-XS/XS.pm	2013/11/22 16:00:30	1.23
+++ CBOR-XS/XS.pm	2013/11/22 16:18:59	1.24
@@ -73,7 +73,7 @@
 
 use common::sense;
 
-our $VERSION = 0.08;
+our $VERSION = 0.09;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -235,7 +235,42 @@
 
 =item $cb_or_undef = $cbor->get_filter
 
-TODO
+Sets or replaces the tagged value decoding filter (when C<$cb> is
+specified) or clears the filter (if no argument or C<undef> is provided).
+
+The filter callback is called only during decoding, when a non-enforced
+tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
+list of enforced tags). For specific tags, it's often better to provide a
+default converter using the C<%CBOR::XS::FILTER> hash (see below).
+
+The first argument is the numerical tag, the second is the (decoded) value
+that has been tagged.
+
+The filter function should return either exactly one value, which will
+replace the tagged value in the decoded data structure, or no values,
+which will result in default handling, which currently means the decoder
+creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
+
+When the filter is cleared (the default state), the default filter
+function, C<CBOR::XS::default_filter>, is used. This function simply looks
+up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
+a code reference that is called with tag and value, and is responsible for
+decoding the value. If no entry exists, it returns no values.
+
+Example: decode all tags not handled internally into CBOR::XS::Tagged
+objects, with no other special handling (useful when working with
+potentially "unsafe" CBOR data).
+
+   CBOR::XS->new->filter (sub { })->decode ($cbor_data);
+
+Example: provide a global filter for tag 1347375694, converting the value
+into some string form.
+
+   $CBOR::XS::FILTER{1347375694} = sub {
+      my ($tag, $value);
+
+      "tag 1347375694 value $value"
+   };
 
 =item $cbor_data = $cbor->encode ($perl_scalar)
 
@@ -672,11 +707,11 @@
 
 =back
 
-=head2 OPTIONAL TAGS
+=head2 NON-ENFORCED TAGS
 
 These tags have default filters provided when decoding. Their handling can
 be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
-providing a custom C<filter> function when decoding.
+providing a custom C<filter> callback when decoding.
 
 When they result in decoding into a specific Perl class, the module
 usually provides a corresponding C<TO_CBOR> method as well.