time: document that going to sleep may stop the monotonic clock

Fixes #23178

Change-Id: I060a73d6263bc135f5a14c1991932a225208bb39
Reviewed-on: https://go-review.googlesource.com/103396
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/time/time.go b/src/time/time.go
index 6579639740987ce606d95669aaa824e3985fbcb5..02452d1c1f07e396850178d3d26c0f4d36dbc196 100644 (file)
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -51,6 +51,10 @@
 // readings. If either t or u contains no monotonic clock reading, these
 // operations fall back to using the wall clock readings.
 //
+// On some systems the monotonic clock will stop if the computer goes to sleep.
+// On such a system, t.Sub(u) may not accurately reflect the actual
+// time that passed between t and u.
+//
 // Because the monotonic clock reading has no meaning outside
 // the current process, the serialized forms generated by t.GobEncode,
 // t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic