encoding/json: please document that float +inf/-inf/nan will cause json.Marshal return error

[bronze1man]

What version of Go are you using (go version)?
go version go1.19.2 darwin/amd64

Does this issue reproduce with the latest release?
It does with go playground

What did you do?
Same as #3480

https://play.golang.org/p/K4xwS7iy4MP

What did you expect to see?
Document that float +inf/-inf/nan will cause json.Marshal return error or Not throwing serialization errors on basic numeric data types with valid state.

What did you see instead?
No document of this kind of thing and return json: unsupported value: NaN

Should golang standard library document possible/common error type of a package or a function like windows api document(https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-deletefilew) or linux man (https://linux.die.net/man/3/mmap)?
Code with standard library sometime looks like try and fix again and again without document of possible/common error type.

reference:

• https://stackoverflow.com/questions/1423081/json-left-out-infinity-and-nan-json-status-in-ecmascript
• encoding/json: handle NaN and Inf #3480
• encoding/json: unsupported value: NaN #25721
• https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-deletefilew
• https://linux.die.net/man/3/mmap

[dr2chase]

@rsc @dsnet @mvdan

[dsnet]

I don't think we can change the behavior, so documenting it seems best.

For the record, as part of #21990, I proposed extending the concept of type-specific format flags to handle non-finite floating point values.

[bronze1man]

@dsnet
Agree with you.
If we can not change the behavior, then we should document all the odd behaviors(another one
#20555), and make the caller to decide whether use this library or use another one base on his need.
I do not need to work with float64/float32 and +inf/-inf/nan. So I am ok with current encoding/json.
I just find this problem from view the source code when I am writing another json library with paste and copy .

[gopherbot]

Change https://go.dev/cl/496142 mentions this issue: encoding/json: document unsupported float values