Comments on exported types and funcs

Author: bboreham

pkg/util/backoff.go

@@ -5,12 +5,14 @@ import (
 	"time"
 )
 
+// BackoffConfig configures a Backoff
 type BackoffConfig struct {
 	MinBackoff time.Duration // start backoff at this level
 	MaxBackoff time.Duration // increase exponentially to this level
 	MaxRetries int           // give up after this many; zero means infinite retries
 }
 
+// Backoff implements exponential backoff with randomized wait times
 type Backoff struct {
 	cfg        BackoffConfig
 	done       <-chan struct{}
@@ -19,6 +21,7 @@ type Backoff struct {
 	duration   time.Duration
 }
 
+// NewBackoff creates a Backoff object. Pass a 'done' channel that can be closed to terminate the operation.
 func NewBackoff(cfg BackoffConfig, done <-chan struct{}) *Backoff {
 	return &Backoff{
 		cfg:      cfg,
@@ -27,25 +30,32 @@ func NewBackoff(cfg BackoffConfig, done <-chan struct{}) *Backoff {
 	}
 }
 
+// Reset the Backoff back to its initial condition
 func (b *Backoff) Reset() {
 	b.numRetries = 0
 	b.cancelled = false
 	b.duration = b.cfg.MinBackoff
 }
 
+// Ongoing returns true if caller should keep going
 func (b *Backoff) Ongoing() bool {
 	return !b.cancelled && (b.cfg.MaxRetries == 0 || b.numRetries < b.cfg.MaxRetries)
 }
 
+// NumRetries returns the number of retries so far
 func (b *Backoff) NumRetries() int {
 	return b.numRetries
 }
 
+// Wait sleeps for the backoff time then increases the retry count and backoff time
+// Returns immediately if done channel is closed
 func (b *Backoff) Wait() {
 	b.numRetries++
 	b.WaitWithoutCounting()
 }
 
+// WaitWithoutCounting sleeps for the backoff time then increases backoff time
+// Returns immediately if done channel is closed
 func (b *Backoff) WaitWithoutCounting() {
 	if b.Ongoing() {
 		select {