--- JSON-XS/XS.pm	2008/03/26 01:43:14	1.97
+++ JSON-XS/XS.pm	2008/05/08 15:33:06	1.104
@@ -1,9 +1,9 @@
 =head1 NAME
 
-=encoding utf-8
-
 JSON::XS - JSON serialising/deserialising, done correctly and fast
 
+=encoding utf-8
+
 JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
            (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
 
@@ -105,7 +105,7 @@
 
 use strict;
 
-our $VERSION = '2.1';
+our $VERSION = '2.2';
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_json decode_json to_json from_json);
@@ -465,6 +465,22 @@
    JSON::XS->new->allow_nonref->encode ("Hello, World!")
    => "Hello, World!"
 
+=item $json = $json->allow_unknown ([$enable])
+
+=item $enabled = $json->get_allow_unknown
+
+If C<$enable> is true (or missing), then C<encode> will I<not> throw an
+exception when it encounters values it cannot represent in JSON (for
+example, filehandles) but instead will encode a JSON C<null> value. Note
+that blessed objects are not included here and are handled separately by
+c<allow_nonref>.
+
+If C<$enable> is false (the default), then C<encode> will throw an
+exception when it encounters anything it cannot encode as JSON.
+
+This option does not affect C<decode> in any way, and it is recommended to
+leave it off unless you know your communications partner.
+
 =item $json = $json->allow_blessed ([$enable])
 
 =item $enabled = $json->get_allow_blessed
@@ -614,9 +630,9 @@
 =item $max_depth = $json->get_max_depth
 
 Sets the maximum nesting level (default C<512>) accepted while encoding
-or decoding. If the JSON text or Perl data structure has an equal or
-higher nesting level then this limit, then the encoder and decoder will
-stop and croak at that point.
+or decoding. If a higher nesting level is detected in JSON text or a Perl
+data structure, then the encoder and decoder will stop and croak at that
+point.
 
 Nesting level is defined by number of hash- or arrayrefs that the encoder
 needs to traverse to reach a given point or the number of C<{> or C<[>
@@ -626,9 +642,12 @@
 Setting the maximum depth to one disallows any nesting, so that ensures
 that the object is only a single hash/object or array.
 
-The argument to C<max_depth> will be rounded up to the next highest power
-of two. If no argument is given, the highest possible setting will be
-used, which is rarely useful.
+If no argument is given, the highest possible setting will be used, which
+is rarely useful.
+
+Note that nesting is implemented by recursion in C. The default value has
+been chosen to be as large as typical operating systems allow without
+crashing.
 
 See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
 
@@ -638,13 +657,12 @@
 
 Set the maximum length a JSON text may have (in bytes) where decoding is
 being attempted. The default is C<0>, meaning no limit. When C<decode>
-is called on a string longer then this number of characters it will not
+is called on a string that is longer then this many bytes, it will not
 attempt to decode the string but throw an exception. This setting has no
 effect on C<encode> (yet).
 
-The argument to C<max_size> will be rounded up to the next B<highest>
-power of two (so may be more than requested). If no argument is given, the
-limit check will be deactivated (same as when C<0> is specified).
+If no argument is given, the limit check will be deactivated (same as when
+C<0> is specified).
 
 See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
 
@@ -685,7 +703,7 @@
 
 =head1 INCREMENTAL PARSING
 
-[This section is still EXPERIMENTAL]
+[This section and the API it details is still EXPERIMENTAL]
 
 In some cases, there is the need for incremental parsing of JSON
 texts. While this module always has to keep both JSON text and resulting
@@ -999,7 +1017,7 @@
 C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
 also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
 
-   encode_json [\0,JSON::XS::true]      # yields [false,true]
+   encode_json [\0, JSON::XS::true]      # yields [false,true]
 
 =item JSON::XS::true, JSON::XS::false
 
@@ -1216,8 +1234,9 @@
 a very short single-line JSON string (also available at
 L<http://dist.schmorp.de/misc/json/short.json>).
 
-   {"method": "handleMessage", "params": ["user1", "we were just talking"], \
-   "id": null, "array":[1,11,234,-5,1e5,1e7, true,  false]}
+   {"method": "handleMessage", "params": ["user1",
+   "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
+   true,  false]}
 
 It shows the number of encodes/decodes per second (JSON::XS uses
 the functional interface, while JSON::XS/2 uses the OO interface
@@ -1325,9 +1344,8 @@
 =head1 BUGS
 
 While the goal of this module is to be correct, that unfortunately does
-not mean it's bug-free, only that I think its design is bug-free. It is
-still relatively early in its development. If you keep reporting bugs they
-will be fixed swiftly, though.
+not mean it's bug-free, only that I think its design is bug-free. If you
+keep reporting bugs they will be fixed swiftly, though.
 
 Please refrain from using rt.cpan.org or any other bug reporting
 service. I put the contact address into my modules for a reason.