time: make it clear that time.Time values do not compare with ==

LGTM=bradfitz, josharian, adg, rsc
R=golang-codereviews, bradfitz, josharian, rsc, adg
CC=golang-codereviews
https://golang.org/cl/141340043

diff --git a/src/time/time.go b/src/time/time.go
index 4f76d79ee59a3ff60b730e8fcf0ba8c0974c2000..0300e846a4b142970d9123cbe567524594747c7b 100644 (file)
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -31,6 +31,11 @@ import "errors"
 // change the instant in time being denoted and therefore does not affect the
 // computations described in earlier paragraphs.
 //
+// Note that the Go == operator compares not just the time instant but also the
+// Location. Therefore, Time values should not be used as map or database keys
+// without first guaranteeing that the identical Location has been set for all
+// values, which can be achieved through use of the UTC or Local method.
+//
 type Time struct {
        // sec gives the number of seconds elapsed since
        // January 1, year 1 00:00:00 UTC.