--- JSON-XS/XS.pm	2013/10/29 00:06:40	1.145
+++ JSON-XS/XS.pm	2013/10/29 00:21:10	1.149
@@ -469,26 +469,28 @@
 
 =item $enabled = $json->get_allow_blessed
 
+See L<OBJECT SERIALISATION> for details.
+
 If C<$enable> is true (or missing), then the C<encode> method will not
-barf when it encounters a blessed reference. Instead, the value of the
-B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
-disabled or no C<TO_JSON> method found) or a representation of the
-object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
-encoded. Has no effect on C<decode>.
+barf when it encounters a blessed reference that it cannot convert
+otherwise. Instead, a JSON C<null> value is encoded instead of the object.
 
 If C<$enable> is false (the default), then C<encode> will throw an
-exception when it encounters a blessed object.
+exception when it encounters a blessed object that it cannot convert
+otherwise.
+
+This setting has no effect on C<decode>.
 
 =item $json = $json->convert_blessed ([$enable])
 
 =item $enabled = $json->get_convert_blessed
 
+See L<OBJECT SERIALISATION> for details.
+
 If C<$enable> is true (or missing), then C<encode>, upon encountering a
 blessed object, will check for the availability of the C<TO_JSON> method
-on the object's class. If found, it will be called in scalar context
-and the resulting scalar will be encoded instead of the object. If no
-C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
-to do.
+on the object's class. If found, it will be called in scalar context and
+the resulting scalar will be encoded instead of the object.
 
 The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
 returns other blessed objects, those will be handled in the same
@@ -498,12 +500,28 @@
 usually in upper case letters and to avoid collisions with any C<to_json>
 function or method.
 
-This setting does not yet influence C<decode> in any way, but in the
-future, global hooks might get installed that influence C<decode> and are
-enabled by this setting.
+If C<$enable> is false (the default), then C<encode> will not consider
+this type of conversion.
+
+This setting has no effect on C<decode>.
 
-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->allow_tags ([$enable])
+
+=item $enabled = $json->allow_tags
+
+See L<OBJECT SERIALISATION> for details.
+
+If C<$enable> is true (or missing), then C<encode>, upon encountering a
+blessed object, will check for the availability of the C<FREEZE> method on
+the object's class. If found, it will be used to serialise the object into
+a nonstandard tagged JSON value (that JSON decoders cannot decode).
+
+It also causes C<decode> to parse such tagged JSON values and deserialise
+them via a call to the C<THAW> method.
+
+If C<$enable> is false (the default), then C<encode> will not consider
+this type of conversion, and tagged JSON values will cause a parse error
+in C<decode>, as if tags were not part of the grammar.
 
 =item $json = $json->filter_json_object ([$coderef->($hashref)])
 
@@ -1001,7 +1019,7 @@
 I<tag> must be a perl package/class name encoded as a JSON string, and the
 I<value> must be a JSON array encoding optional constructor arguments.
 
-See "OBJECT SERIALISATION", below, for details.
+See L<OBJECT SERIALISATION>, below, for details.
 
 =back
 
@@ -1050,7 +1068,7 @@
 =item blessed objects
 
 Blessed objects are not directly representable in JSON, but C<JSON::XS>
-allows various ways of handling objects. See "OBJECT SERIALISATION",
+allows various ways of handling objects. See L<OBJECT SERIALISATION>,
 below, for details.
 
 =item simple scalars
@@ -1113,7 +1131,7 @@
 
 =over 4
 
-=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method.
+=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
 
 In this case, C<JSON::XS> uses the L<Types::Serialiser> object
 serialisation protocol to create a tagged JSON value, using a nonstandard
@@ -1138,7 +1156,7 @@
       ($self->{type}, $self->{id})
    }
 
-=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method.
+=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
 
 In this case, the C<TO_JSON> method of the object is invoked in scalar
 context. It must return a single scalar that can be directly encoded into
@@ -1178,8 +1196,9 @@
 error will result (as if tagged values were not part of the grammar).
 
 If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method
-of the package/classname used during serialisation. If there is no such
-method, the decoding will fail with an error.
+of the package/classname used during serialisation (it will not attempt
+to load the package as a Perl module). If there is no such method, the
+decoding will fail with an error.
 
 Otherwise, the C<THAW> method is invoked with the classname as first
 argument, the constant string C<JSON> as second argument, and all the