cmp: document ordering for floating point values in cmp.Ordered

[robpike]

Although the information is scattered about elsewhere, it would be good for the documentation for cmp.Ordered to explain how NaNs work. Then, the documentation for builtin.min and builtin.max should reference the documentation for cmp.Ordered directly (it does indirectly through the declaration).

[ianlancetaylor]

Although cmp.Ordered doesn't say anything about NaNs, we do document NaN behavior for both cmp.Compare and cmp.Less. The spec documents NaN behavior for min and max (https://tip.golang.org/ref/spec#Min_and_max), though I guess we don't currently say anything in the builtin package docs.

[robpike]

It's fine if they all cross-reference one another, but it should also be documented in the libraries as well as the spec. I would be unlikely to think of going to the spec to read how cmp.Ordered works, for example.

[dr2chase]

@rsc @ianlancetaylor do we plan to get this done for 1.21?

[gopherbot]

Change https://go.dev/cl/502235 mentions this issue: cmp, builtin: document NaN behavior