--- JSON-XS/XS.pm	2010/03/11 17:36:09	1.130
+++ JSON-XS/XS.pm	2010/03/11 19:31:37	1.131
@@ -66,10 +66,10 @@
 =item * round-trip integrity
 
 When you serialise a perl data structure using only data types supported
-by JSON, the deserialised data structure is identical on the Perl level.
-(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
-like a number). There minor I<are> exceptions to this, read the MAPPING
-section below to learn about those.
+by JSON and Perl, the deserialised data structure is identical on the Perl
+level. (e.g. the string "2.0" doesn't suddenly become "2" just because
+it looks like a number). There I<are> minor exceptions to this, read the
+MAPPING section below to learn about those.
 
 =item * strict checking of JSON correctness
 
@@ -996,6 +996,11 @@
 precision (in which case you might lose perfect roundtripping ability, but
 the JSON number will still be re-encoded as a JSON number).
 
+Note that precision is not accuracy - binary floating point values cannot
+represent most decimal fractions exactly, and when converting from and to
+floating point, JSON::XS only guarantees precision up to but not including
+the leats significant bit.
+
 =item true, false
 
 These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
@@ -1092,6 +1097,13 @@
 if you need this capability (but don't forget to explain why it's needed
 :).
 
+Note that numerical precision has the same meaning as under Perl (so
+binary to decimal conversion follows the same rules as in Perl, which
+can differ to other languages). Also, your perl interpreter might expose
+extensions to the floating point numbers of your platform, such as
+infinities or NaN's - these cannot be represented in JSON, and it is an
+error to pass those in.
+
 =back