From 36e4eaff991eb0bcb9bb6bd5c2244ce670a8768d Mon Sep 17 00:00:00 2001
From: Adrien Delorme <adrien.delorme@icloud.com>
Date: Tue, 11 Jun 2019 12:20:00 +0200
Subject: [PATCH] document retry.Backoff better

---
 common/retry/retry.go | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/common/retry/retry.go b/common/retry/retry.go
index 2b1a4f231..3189c4c97 100644
--- a/common/retry/retry.go
+++ b/common/retry/retry.go
@@ -76,12 +76,23 @@ func (cfg Config) Run(ctx context.Context, fn func(context.Context) error) error
 	}
 }
 
+// Backoff is a self contained backoff time calculator. This struct should be
+// passed around as a copy as it changes its own fields upon any Backoff call.
+// Backoff is not thread safe. For now only a Linear backoff call is
+// implemented and the Exponential call will be implemented when needed.
 type Backoff struct {
+	// Initial time to wait. A Backoff call will change this value.
 	InitialBackoff time.Duration
-	MaxBackoff     time.Duration
-	Multiplier     float64
+	// Maximum time returned.
+	MaxBackoff time.Duration
+	// For a Linear backoff, InitialBackoff will be multiplied by Multiplier
+	// after each call.
+	Multiplier float64
 }
 
+// Linear Backoff returns a linearly increasing Duration.
+//  n = n * Multiplier.
+// the first value of n is InitialBackoff. n is maxed by MaxBackoff.
 func (lb *Backoff) Linear() time.Duration {
 	wait := lb.InitialBackoff
 	lb.InitialBackoff = time.Duration(lb.Multiplier * float64(lb.InitialBackoff))
@@ -90,3 +101,8 @@ func (lb *Backoff) Linear() time.Duration {
 	}
 	return wait
 }
+
+// Exponential backoff panics: not implemented, yet.
+func (lb *Backoff) Exponential() time.Duration {
+	panic("not implemented, yet")
+}