From f551f5e8281ca82499d73df6e92949804b177f15 Mon Sep 17 00:00:00 2001
From: Spike Curtis <spike@coder.com>
Date: Tue, 25 Jun 2024 16:24:16 +0400
Subject: [PATCH] feat: add docstrings to mock timer and ticker methods and
 structs

---
 clock/ticker.go |  7 +++++++
 clock/timer.go  | 12 ++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/clock/ticker.go b/clock/ticker.go
index 0ef68f91b5027..43700f31d4635 100644
--- a/clock/ticker.go
+++ b/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)
diff --git a/clock/timer.go b/clock/timer.go
index 8735fc05b9a99..b0cf0b33ac07d 100644
--- a/clock/timer.go
+++ b/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)