[ADD] comments

Author: searKing

Diff for: go/time/timer.go

@@ -1,8 +1,9 @@
 package time
 
 import (
-	"github.com/searKing/golang/go/sync/atomic"
 	"time"
+
+	"github.com/searKing/golang/go/sync/atomic"
 )
 
 // https://github.com/golang/go/issues/27169
@@ -12,14 +13,23 @@ type Timer struct {
 	chanConsumed atomic.Bool
 }
 
-//saw channel read, must be called after receiving value from timer chan
+// saw channel read, must be called after receiving value from timer chan
+// an example case is AfterFunc bellow.
 func (t *Timer) ChanConsumed() {
 	t.chanConsumed.Store(true)
 }
 
+// Reset changes the timer to expire after duration d.
+// It returns true if the timer had been active, false if the timer had
+// expired or been stopped.
+// Reset can be invoked anytime, which enhances std time.Reset
+// that should be invoked only on stopped or expired timers with drained channels,
 func (t *Timer) Reset(d time.Duration) bool {
 	ret := t.Stop()
 	if !ret && !t.chanConsumed.Load() {
+		// drain the channel, prevents the Timer from blocking on Send to t.C by sendTime, t.C is reused.
+		// The underlying Timer is not recovered by the garbage collector until the timer fires.
+		// consume the channel only once for the channel can be triggered only one time at most before Stop is called.
 		<-t.C
 	}
 	t.Timer.Reset(d)