time: clarify Unix, UnixNano, and In a bit

Fixes #23316

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

diff --git a/src/time/time.go b/src/time/time.go
index 02452d1c1f07e396850178d3d26c0f4d36dbc196..2374043ea3cc64cd59cd7dc3a83b05f01a5e1edc 100644 (file)
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -1076,7 +1076,9 @@ func (t Time) Local() Time {
        return t
 }
 
-// In returns t with the location information set to loc.
+// In returns a copy of t representating the same time instant, but
+// with the copy's location information set to loc for display
+// purposes.
 //
 // In panics if loc is nil.
 func (t Time) In(loc *Location) Time {
@@ -1104,7 +1106,8 @@ func (t Time) Zone() (name string, offset int) {
 }
 
 // Unix returns t as a Unix time, the number of seconds elapsed
-// since January 1, 1970 UTC.
+// since January 1, 1970 UTC. The result does not depend on the
+// location associated with t.
 func (t Time) Unix() int64 {
        return t.unixSec()
 }
@@ -1113,7 +1116,8 @@ func (t Time) Unix() int64 {
 // since January 1, 1970 UTC. The result is undefined if the Unix time
 // in nanoseconds cannot be represented by an int64 (a date before the year
 // 1678 or after 2262). Note that this means the result of calling UnixNano
-// on the zero Time is undefined.
+// on the zero Time is undefined. The result does not depend on the
+// location associated with t.
 func (t Time) UnixNano() int64 {
        return (t.unixSec())*1e9 + int64(t.nsec())
 }