feat: add docstrings to mock timer and ticker methods and structs (#13658)

clock/ticker.go

@@ -2,6 +2,7 @@ package clock
 
 import "time"
 
+// A Ticker holds a channel that delivers “ticks” of a clock at intervals.
 type Ticker struct {
 	C <-chan time.Time
 	//nolint: revive
@@ -33,6 +34,9 @@ func (t *Ticker) next() time.Time {
 	return t.nxt
 }
 
+// Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does
+// not close the channel, to prevent a concurrent goroutine reading from the
+// channel from seeing an erroneous "tick".
 func (t *Ticker) Stop(tags ...string) {
 	if t.ticker != nil {
 		t.ticker.Stop()
@@ -47,6 +51,9 @@ func (t *Ticker) Stop(tags ...string) {
 	t.stopped = true
 }
 
+// Reset stops a ticker and resets its period to the specified duration. The
+// next tick will arrive after the new period elapses. The duration d must be
+// greater than zero; if not, Reset will panic.
 func (t *Ticker) Reset(d time.Duration, tags ...string) {
 	if t.ticker != nil {
 		t.ticker.Reset(d)

clock/timer.go

@@ -2,6 +2,9 @@ package clock
 
 import "time"
 
+// The Timer type represents a single event. When the Timer expires, the current time will be sent
+// on C, unless the Timer was created by AfterFunc. A Timer must be created with NewTimer or
+// AfterFunc.
 type Timer struct {
 	C <-chan time.Time
 	//nolint: revive
@@ -26,6 +29,11 @@ func (t *Timer) next() time.Time {
 	return t.nxt
 }
 
+// Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the
+// timer has already expired or been stopped. Stop does not close the channel, to prevent a read
+// from the channel succeeding incorrectly.
+//
+// See https://pkg.go.dev/time#Timer.Stop for more information.
 func (t *Timer) Stop(tags ...string) bool {
 	if t.timer != nil {
 		return t.timer.Stop()
@@ -40,6 +48,10 @@ func (t *Timer) Stop(tags ...string) bool {
 	return result
 }
 
+// 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.
+//
+// See https://pkg.go.dev/time#Timer.Reset for more information.
 func (t *Timer) Reset(d time.Duration, tags ...string) bool {
 	if t.timer != nil {
 		return t.timer.Reset(d)