math/big: Float.Copy doc string can be misleading

[griesemer]

Reminder issue to review this documentation in math/big:

// Copy sets z to x, with the same precision, rounding mode, and
// accuracy as x, and returns z. x is not changed even if z and
// x are the same.
func (z *Float) Copy(x *Float) *Float

The 2nd sentence is confusing.

[robpike]

I was bitten by this because if x and z are the same, as in y := x.Copy(x), which seems prima facie to be how one might use this, it doesn't do what it looks like: x and y are now the same memory, despite y looking like it's a copy.

Perhaps some examples would help (there are none). Also the last sentence might instead be:

If x and z are the same Float, x will not be changed but the return value will also not be a copy of x.

[gopherbot]

Change https://go.dev/cl/590635 mentions this issue: math/big: better doc string for Float.Copy, add example test