time: clarify when draining a Timer's channel is needed

Updates golang#27169

Author: darkfeline

src/time/sleep.go

@@ -54,9 +54,10 @@ type Timer struct {
 // Stop does not close the channel, to prevent a read from the channel succeeding
 // incorrectly.
 //
-// To prevent a timer created with NewTimer from firing after a call to Stop,
-// check the return value and drain the channel.
-// For example, assuming the program has not received from t.C already:
+// Programs should handle the case in which the timer fires just as
+// Stop is called by checking the return value.
+// For example, if t.C needs to be drained before calling Reset and
+// assuming the program has not received from t.C already:
 //
 // 	if !t.Stop() {
 // 		<-t.C
@@ -97,10 +98,9 @@ func NewTimer(d Duration) *Timer {
 // It returns true if the timer had been active, false if the timer had
 // expired or been stopped.
 //
-// Resetting a timer must take care not to race with the send into t.C
-// that happens when the current timer expires.
+// Reset should always be invoked on stopped or expired timers with a drained channel.
 // If a program has already received a value from t.C, the timer is known
-// to have expired, and t.Reset can be used directly.
+// to have expired and the channel drained, so t.Reset can be used directly.
 // If a program has not yet received a value from t.C, however,
 // the timer must be stopped and—if Stop reports that the timer expired
 // before being stopped—the channel explicitly drained: