--- JSON-XS/XS.pm	2007/07/02 01:12:27	1.51
+++ JSON-XS/XS.pm	2007/07/02 02:57:11	1.52
@@ -350,7 +350,7 @@
 If C<$enable> is false, then the C<allow_blessed> setting will decide what
 to do when a blessed object is found.
 
-=item $json = $json->filter_json_object ([$coderef])
+=item $json = $json->filter_json_object ([$coderef->($hashref)])
 
 When C<$coderef> is specified, it will be called from C<decode> each
 time it decodes a JSON object. The only argument is a reference to the
@@ -361,28 +361,33 @@
 original deserialised hash will be inserted. This setting can slow down
 decoding considerably.
 
-When C<$coderef> is omitted or undefined, C<decode> will not change the
-deserialised hash in any way. This is maximally fast.
+When C<$coderef> is omitted or undefined, any existing callback will
+be removed and C<decode> will not change the deserialised hash in any
+way.
 
 Example, convert all JSON objects into the integer 5:
 
    my $js = JSON::XS->new->filter_json_object (sub { 5 });
    # returns [5]
    $js->decode ('[{}]')
-   # throw an exception because allow_nonref is not enabled:
+   # throw an exception because allow_nonref is not enabled
+   # so a lone 5 is not allowed.
    $js->decode ('{"a":1, "b":2}');
 
-=item $json = $json->filter_json_single_key_object ([$coderef])
+=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
 
-Works like C<filter_json_object>, but is only called for JSON objects
-having only a single key.
+Works remotely similar to C<filter_json_object>, but is only called for
+JSON objects having a single key named C<$key>.
 
 This C<$coderef> is called before the one specified via
-C<filter_json_object>, if any. If it returns something, that will be
-inserted into the data structure. If it returns nothing, the callback
-from C<filter_json_object> will be called next. If you want to force
-insertion of single-key objects even in the presence of a mutating
-C<filter_json_object> callback, simply return the passed hash.
+C<filter_json_object>, if any. It gets passed the single value in the JSON
+object. If it returns a single value, it will be inserted into the data
+structure. If it returns nothing (not even C<undef> but the empty list),
+the callback from C<filter_json_object> will be called next, as if no
+single-key callback were specified.
+
+If C<$coderef> is omitted or undefined, the corresponding callback will be
+disabled. There can only ever be one callback for a given key.
 
 As this callback gets called less often then the C<filter_json_object>
 one, decoding speed will not usually suffer as much. Therefore, single-key
@@ -403,10 +408,8 @@
    # return whatever is in $WIDGET{5}:
    JSON::XS
       ->new
-      ->filter_json_single_key_object (sub {
-         exists $_[0]{__widget__}
-            ? $WIDGET{ $_[0]{__widget__} }
-            : ()
+      ->filter_json_single_key_object (__widget__ => sub {
+            $WIDGET{ $_[0] }
          })
       ->decode ('{"__widget__": 5')