time: update Timer.Stop doc to account for AfterFunc

Fixes #17600.

Change-Id: I7aa0eb0dd959da031b6039b51f07db668d4fb468
Reviewed-on: https://go-review.googlesource.com/33131
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Ian Gudger <igudger@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/time/sleep.go b/src/time/sleep.go
index 8e5c8254f149de690b08356fc1cd921ea02a9aea..4b01404896eccfa3c427dafbcc680b21f8b7bfad 100644 (file)
--- a/src/time/sleep.go
+++ b/src/time/sleep.go
@@ -55,7 +55,7 @@ type Timer struct {
 // Stop does not close the channel, to prevent a read from the channel succeeding
 // incorrectly.
 //
-// To prevent the timer firing after a call to Stop,
+// 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:
 //
@@ -65,6 +65,12 @@ type Timer struct {
 //
 // This cannot be done concurrent to other receives from the Timer's
 // channel.
+//
+// For a timer created with AfterFunc(d, f), if t.Stop returns false, then the timer
+// has already expired and the function f has been started in its own goroutine;
+// Stop does not wait for f to complete before returning.
+// If the caller needs to know whether f is completed, it must coordinate
+// with f explicitly.
 func (t *Timer) Stop() bool {
        if t.r.f == nil {
                panic("time: Stop called on uninitialized Timer")