Please clarify what documentation you feel needs updated (and how it may be worded). Also, I assume you mean json_decode(), right?

And for good measure, the source code:
http://cvs.php.net/viewvc.cgi/php-src/ext/json/json.c?view=markup

Hmm

Yes I meant json_decode, however the json_decode function relies on the JSON_parser function which is a parser I can't read very well.
I guess the parsing is OK.

When you pass "true", "false" or "null" than this will return TRUE, FALSE or NULL. This isn't part of the "official" JSON standard:

http://www.ietf.org/rfc/rfc4627.txt

Also for input which begins and end with '"' (but not "'") the string will be returned (including escaping of \n, \uxxxx etc).

when the string starts with '{' or '[' but the JSON_parser fails NULL will be returned. This is only done for the very first character (hence the "unexpected" behaviour in 45989).

In all other cases the string is returned as it was passed to the function.

Below is my mediocre attempt to rewrite the Return Values section of json_decode. I believe the info is correct, but it is somewhat long and could be more consice. English is not my first language...

===
Return Values
A mix of objects (of type stdclass) and arrays which resembles the $json string, or if the optional assoc parameter is TRUE, associated arrays are used instead of objects.
If the internal json parser fails, this function tries to detect simple javascript literals including: true, false, null and the literal, double qouted string.
Strings which start with '{' or '[' cause this function to return NULL (only if the json parser fails), because this could have been a json object/array.
Otherwise the string itself is returned.

===

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.

Works well at least in PHP 5.3.1.