--- JSON-XS/XS.pm	2007/03/23 17:48:59	1.11
+++ JSON-XS/XS.pm	2007/03/23 18:33:50	1.12
@@ -6,6 +6,17 @@
 
  use JSON::XS;
 
+ # exported functions, croak on error
+
+ $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
+ $perl_hash_or_arrayref  = from_json $utf8_encoded_json_text;
+
+ # oo-interface
+
+ $coder = JSON::XS->new->ascii->pretty->allow_nonref;
+ $pretty_printed_unencoded = $coder->encode ($perl_scalar);
+ $perl_scalar = $coder->decode ($unicode_json_text);
+
 =head1 DESCRIPTION
 
 This module converts Perl data structures to JSON and vice versa. Its
@@ -149,12 +160,16 @@
 unicode string.  Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
 to be done yourself, e.g. using the Encode module.
 
+Example, output UTF-16-encoded JSON:
+
 =item $json = $json->pretty ([$enable])
 
 This enables (or disables) all of the C<indent>, C<space_before> and
 C<space_after> (and in the future possibly more) flags in one call to
 generate the most readable (or most compact) form possible.
 
+Example, pretty-print some simple structure:
+
    my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
    =>
    {
@@ -186,6 +201,10 @@
 This setting has no effect when decoding JSON strings. You will also most
 likely combine this setting with C<space_after>.
 
+Example, space_before enabled, space_after and indent disabled:
+
+   {"key" :"value"}
+
 =item $json = $json->space_after ([$enable])
 
 If C<$enable> is true (or missing), then the C<encode> method will add an extra
@@ -198,6 +217,10 @@
 
 This setting has no effect when decoding JSON strings.
 
+Example, space_before and indent disabled, space_after enabled:
+
+   {"key": "value"}
+
 =item $json = $json->canonical ([$enable])
 
 If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
@@ -226,6 +249,12 @@
 or array. Likewise, C<decode> will croak if given something that is not a
 JSON object or array.
 
+Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
+resulting in an invalid JSON text:
+
+   JSON::XS->new->allow_nonref->encode ("Hello, World!")
+   => "Hello, World!"
+
 =item $json = $json->shrink ([$enable])
 
 Perl usually over-allocates memory a bit when allocating space for
@@ -514,13 +543,10 @@
 Again, JSON::XS leads by far in the encoding case, while still beating
 every other module in the decoding case.
 
-Last example is an almost 8MB large hash with many large binary values
-(PNG files), resulting in a lot of escaping:
-
 =head1 RESOURCE LIMITS
 
 JSON::XS does not impose any limits on the size of JSON texts or Perl
-values they represent - if your machine cna handle it, JSON::XS will
+values they represent - if your machine can handle it, JSON::XS will
 encode or decode it. Future versions might optionally impose structure
 depth and memory use resource limits.