Merge pull request #10 from vimeo/docblock-update

Clarify some Docstrings

clock.go

@@ -68,7 +68,7 @@ type Clock interface {
 	Until(time.Time) time.Duration
 	// SleepUntil blocks until either ctx expires or until arrives.
 	// Return value is false if context-cancellation/expiry prompted an
-	// early return
+	// early return.
 	SleepUntil(ctx context.Context, until time.Time) bool
 	// SleepFor is the relative-time equivalent of SleepUntil. In the
 	// default implementation, this is the lower-level method, but other

fake/fake_clock.go

@@ -20,35 +20,35 @@ type Clock struct {
 	// be removed from the map.
 	sleepers map[chan<- struct{}]time.Time
 	// cbs contains a map from a *stopTimer containing the callback
-	// function to the wakeup time. (protected by mu)
+	// function to the wakeup time. (protected by mu).
 	cbs map[*stopTimer]time.Time
 
 	// cbsWG tracks callback goroutines configured from AfterFunc (no mutex
-	// protection necessary)
+	// protection necessary).
 	cbsWG sync.WaitGroup
 
 	// cond is broadcasted() upon any sleep or wakeup event (mutations to
 	// sleepers or cbs).
 	cond sync.Cond
 
-	// counter tracking the number of wakeups (protected by mu)
+	// counter tracking the number of wakeups (protected by mu).
 	wakeups int
 
-	// callbackExecs tracking the number of callback executions (protected by mu)
+	// callbackExecs tracking the number of callback executions (protected by mu).
 	callbackExecs int
 
-	// counter tracking the number of canceled sleeps (protected by mu)
+	// counter tracking the number of canceled sleeps (protected by mu).
 	sleepAborts int
 
-	// counter tracking the number of canceled timers (including AfterFuncs) (protected by mu)
+	// counter tracking the number of canceled timers (including AfterFuncs) (protected by mu).
 	timerAborts int
 
 	// counter tracking the number of sleepers who have ever gone to sleep
-	// (protected by mu)
+	// (protected by mu).
 	sleepersAggregate int
 
 	// counter tracking the number of callbacks that have ever been
-	// registered (via AfterFunc) (protected by mu)
+	// registered (via AfterFunc) (protected by mu).
 	callbacksAggregate int
 }
 
@@ -66,7 +66,7 @@ func NewClock(initialTime time.Time) *Clock {
 	return &fc
 }
 
-// returns the number of sleepers awoken
+// returns the number of sleepers awoken.
 func (f *Clock) setClockLocked(t time.Time, cbRunningWG *sync.WaitGroup) int {
 	awoken := 0
 	for ch, target := range f.sleepers {
@@ -97,9 +97,10 @@ func (f *Clock) setClockLocked(t time.Time, cbRunningWG *sync.WaitGroup) int {
 	return awoken + cbsRun
 }
 
-// SetClock skips the FakeClock to the specified time (forward or backwards)
-// The goroutines running newly-spawned functions scheduled with AfterFunc are
-// guaranteed to have scheduled by the time this function returns.
+// SetClock skips the FakeClock to the specified time (forward or backwards) The
+// goroutines running newly-spawned functions scheduled with AfterFunc are
+// guaranteed to have scheduled by the time this function returns.  It returns
+// the number of sleepers awoken.
 func (f *Clock) SetClock(t time.Time) int {
 	cbsWG := sync.WaitGroup{}
 	// Wait for callbacks to schedule before returning (but after the mutex
@@ -111,9 +112,9 @@ func (f *Clock) SetClock(t time.Time) int {
 }
 
 // Advance skips the FakeClock forward by the specified duration (backwards if
-// negative)
-// The goroutines running newly-spawned functions scheduled with AfterFunc are
-// guaranteed to have scheduled by the time this function returns.
+// negative) The goroutines running newly-spawned functions scheduled with
+// AfterFunc are guaranteed to have scheduled by the time this function returns.
+// It returns number of sleepers awoken.
 func (f *Clock) Advance(dur time.Duration) int {
 	cbsWG := sync.WaitGroup{}
 	// Wait for callbacks to schedule before returning (but after the mutex
@@ -172,7 +173,8 @@ func (f *Clock) RegisteredCallbacks() []time.Time {
 	return out
 }
 
-// AwaitSleepers waits until the number of sleepers exceeds its argument
+// AwaitSleepers waits until the number of sleepers equals or exceeds its
+// argument.
 func (f *Clock) AwaitSleepers(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -181,8 +183,8 @@ func (f *Clock) AwaitSleepers(n int) {
 	}
 }
 
-// AwaitAggSleepers waits until the aggregate number of sleepers exceeds its
-// argument
+// AwaitAggSleepers waits until the aggregate number of sleepers equals or
+// exceeds its argument.
 func (f *Clock) AwaitAggSleepers(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -191,8 +193,8 @@ func (f *Clock) AwaitAggSleepers(n int) {
 	}
 }
 
-// AwaitSleepAborts waits until the number of aborted sleepers exceeds its
-// argument
+// AwaitSleepAborts waits until the number of aborted sleepers equals or exceeds
+// its argument.
 func (f *Clock) AwaitSleepAborts(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -202,7 +204,7 @@ func (f *Clock) AwaitSleepAborts(n int) {
 }
 
 // Wakeups returns the number of sleepers that have been awoken (useful for
-// verifying that nothing was woken up when advancing time)
+// verifying that nothing was woken up when advancing time).
 func (f *Clock) Wakeups() int {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -252,7 +254,7 @@ func (f *Clock) removeWaiter(ch chan struct{}, abort bool) {
 
 // SleepUntil blocks until either ctx expires or until arrives.
 // Return value is false if context-cancellation/expiry prompted an
-// early return
+// early return.
 func (f *Clock) SleepUntil(ctx context.Context, until time.Time) (success bool) {
 	ch := f.setAbsoluteWaiter(until)
 	defer func() { f.removeWaiter(ch, !success) }()
@@ -317,7 +319,7 @@ type doaStopTimer struct{}
 func (doaStopTimer) Stop() bool { return false }
 
 // AfterFunc runs cb after time duration has "elapsed" (by this clock's
-// definition of "elapsed")
+// definition of "elapsed").
 func (f *Clock) AfterFunc(d time.Duration, cb func()) clocks.StopTimer {
 	s := &stopTimer{f: cb, c: f}
 	f.mu.Lock()
@@ -350,23 +352,23 @@ func (f *Clock) NumCallbackExecs() int {
 }
 
 // NumAggCallbacks returns the aggregate number of registered callbacks
-// (via AfterFunc)
+// (via AfterFunc).
 func (f *Clock) NumAggCallbacks() int {
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	return f.callbacksAggregate
 }
 
 // NumTimerAborts returns the aggregate number of registered callbacks (and
-// timers) that have been canceled
+// timers) that have been canceled.
 func (f *Clock) NumTimerAborts() int {
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	return f.timerAborts
 }
 
 // AwaitAggCallbacks waits until the aggregate number of registered callbacks
-// (via AfterFunc) exceeds its argument
+// (via AfterFunc) exceeds its argument.
 func (f *Clock) AwaitAggCallbacks(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -376,15 +378,15 @@ func (f *Clock) AwaitAggCallbacks(n int) {
 }
 
 // NumRegisteredCallbacks returns the aggregate number of registered callbacks
-// (via AfterFunc)
+// (via AfterFunc).
 func (f *Clock) NumRegisteredCallbacks() int {
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	return len(f.cbs)
 }
 
 // AwaitRegisteredCallbacks waits until the number of registered callbacks
-// (via AfterFunc) exceeds its argument
+// (via AfterFunc) exceeds its argument.
 func (f *Clock) AwaitRegisteredCallbacks(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -394,7 +396,7 @@ func (f *Clock) AwaitRegisteredCallbacks(n int) {
 }
 
 // AwaitTimerAborts waits until the aggregate number of registered callbacks
-// (via AfterFunc) exceeds its argument
+// (via AfterFunc) exceeds its argument.
 func (f *Clock) AwaitTimerAborts(n int) {
 	f.mu.Lock()
 	defer f.mu.Unlock()

offset/offset_clock.go

@@ -16,41 +16,40 @@ type Clock struct {
 }
 
 // Now implements Clock, returning the current time (according to the captive
-// clock adjusted by offset)
+// clock adjusted by offset).
 func (o *Clock) Now() time.Time {
 	return o.inner.Now().Add(o.offset)
 }
 
 // Until implements Clock, returning the difference between the current time
-// and its argument (according to the captive clock adjusted by offset)
+// and its argument (according to the captive clock adjusted by offset).
 func (o *Clock) Until(t time.Time) time.Duration {
 	return o.inner.Until(t) + o.offset
 }
 
 // SleepUntil blocks until either ctx expires or until arrives.
 // Return value is false if context-cancellation/expiry prompted an
-// early return
+// early return.
 func (o *Clock) SleepUntil(ctx context.Context, until time.Time) bool {
 	return o.inner.SleepUntil(ctx, until.Add(o.offset))
 }
 
 // SleepFor is the relative-time equivalent of SleepUntil.
 // Return value is false if context-cancellation/expiry prompted an
-// early return
+// early return.
 func (o *Clock) SleepFor(ctx context.Context, dur time.Duration) bool {
 	// SleepFor is relative, so it doesn't need any adjustment
 	return o.inner.SleepFor(ctx, dur)
 }
 
 // AfterFunc executes function f after duration d, (delegating to the wrapped
-// clock, as the time-argument is relative)
+// clock, as the time-argument is relative).
 func (o *Clock) AfterFunc(d time.Duration, f func()) clocks.StopTimer {
 	// relative time, so nothing to do here, just delegate on down.
 	return o.inner.AfterFunc(d, f)
 }
 
-// NewOffsetClock creates an OffsetClock.
-// offset is added to all absolute times
+// NewOffsetClock creates an OffsetClock. offset is added to all absolute times.
 func NewOffsetClock(inner clocks.Clock, offset time.Duration) *Clock {
 	return &Clock{
 		inner:  inner,

timer.go

@@ -1,7 +1,7 @@
 package clocks
 
 // StopTimer exposes a `Stop()` method for an equivalent object to time.Timer
-// (in the defaultClock case, it may be an actual time.Timer)
+// (in the defaultClock case, it may be an actual time.Timer).
 type StopTimer interface {
 	// Stop attempts to prevent a timer from firing, returning true if it
 	// succeeds in preventing the timer from firing, and false if it