math: document sign bit correspondence for floating-point/bits conversions

Fixes #27736.

Change-Id: Ibda7da7ec6e731626fc43abf3e8c1190117f7885
Reviewed-on: https://go-review.googlesource.com/c/153057
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/math/unsafe.go b/src/math/unsafe.go
index 5ae67420f4dc029dfb0bc816378520ef42a09d2d..e59f50ca62e5cc4ecdcc334b319093c5ef6a905d 100644 (file)
--- a/src/math/unsafe.go
+++ b/src/math/unsafe.go
@@ -6,16 +6,24 @@ package math
 
 import "unsafe"
 
-// Float32bits returns the IEEE 754 binary representation of f.
+// Float32bits returns the IEEE 754 binary representation of f,
+// with the sign bit of f and the result in the same bit position.
+// Float32bits(Float32frombits(x)) == x.
 func Float32bits(f float32) uint32 { return *(*uint32)(unsafe.Pointer(&f)) }
 
-// Float32frombits returns the floating point number corresponding
-// to the IEEE 754 binary representation b.
+// Float32frombits returns the floating-point number corresponding
+// to the IEEE 754 binary representation b, with the sign bit of b
+// and the result in the same bit position.
+// Float32frombits(Float32bits(x)) == x.
 func Float32frombits(b uint32) float32 { return *(*float32)(unsafe.Pointer(&b)) }
 
-// Float64bits returns the IEEE 754 binary representation of f.
+// Float64bits returns the IEEE 754 binary representation of f,
+// with the sign bit of f and the result in the same bit position,
+// and Float64bits(Float64frombits(x)) == x.
 func Float64bits(f float64) uint64 { return *(*uint64)(unsafe.Pointer(&f)) }
 
-// Float64frombits returns the floating point number corresponding
-// the IEEE 754 binary representation b.
+// Float64frombits returns the floating-point number corresponding
+// to the IEEE 754 binary representation b, with the sign bit of b
+// and the result in the same bit position.
+// Float64frombits(Float64bits(x)) == x.
 func Float64frombits(b uint64) float64 { return *(*float64)(unsafe.Pointer(&b)) }