Updated comments in wait.go

The comments on the fields of Backoff did not match the behavior of
the Step() method.

The comment on the Step method did not make it clear whether the
returned amount of time to sleep is based on the original or the
revised duration.

The comments on the ExponentialBackoff function did not exactly and
clearly correspond to the actual behavior.

Author: MikeSpreitzer

staging/src/k8s.io/apimachinery/pkg/util/wait/wait.go

@@ -207,23 +207,31 @@ type ConditionFunc func() (done bool, err error)
 type Backoff struct {
 	// The initial duration.
 	Duration time.Duration
-	// Duration is multiplied by factor each iteration. Must be greater
-	// than or equal to zero.
+	// Duration is multiplied by factor each iteration, if factor is not zero
+	// and the limits imposed by Steps and Cap have not been reached.
+	// Should not be negative.
+	// The jitter does not contribute to the updates to the duration parameter.
 	Factor float64
-	// The amount of jitter applied each iteration. Jitter is applied after
-	// cap.
+	// The sleep at each iteration is the duration plus an additional
+	// amount chosen uniformly at random from the interval between
+	// zero and `jitter*duration`.
 	Jitter float64
-	// The number of steps before duration stops changing. If zero, initial
-	// duration is always used. Used for exponential backoff in combination
-	// with Factor.
+	// The remaining number of iterations in which the duration
+	// parameter may change (but progress can be stopped earlier by
+	// hitting the cap). If not positive, the duration is not
+	// changed. Used for exponential backoff in combination with
+	// Factor and Cap.
 	Steps int
-	// The returned duration will never be greater than cap *before* jitter
-	// is applied. The actual maximum cap is `cap * (1.0 + jitter)`.
+	// A limit on revised values of the duration parameter. If a
+	// multiplication by the factor parameter would make the duration
+	// exceed the cap then the duration is set to the cap and the
+	// steps parameter is set to zero.
 	Cap time.Duration
 }
 
-// Step returns the next interval in the exponential backoff. This method
-// will mutate the provided backoff.
+// Step (1) returns an amount of time to sleep determined by the
+// original Duration and Jitter and (2) mutates the provided Backoff
+// to update its Steps and Duration.
 func (b *Backoff) Step() time.Duration {
 	if b.Steps < 1 {
 		if b.Jitter > 0 {
@@ -271,14 +279,14 @@ func contextForChannel(parentCh <-chan struct{}) (context.Context, context.Cance
 
 // ExponentialBackoff repeats a condition check with exponential backoff.
 //
-// It checks the condition up to Steps times, increasing the wait by multiplying
-// the previous duration by Factor.
-//
-// If Jitter is greater than zero, a random amount of each duration is added
-// (between duration and duration*(1+jitter)).
-//
-// If the condition never returns true, ErrWaitTimeout is returned. All other
-// errors terminate immediately.
+// It repeatedly checks the condition and then sleeps, using `backoff.Step()`
+// to determine the length of the sleep and adjust Duration and Steps.
+// Stops and returns as soon as:
+// 1. the condition check returns true or an error,
+// 2. `backoff.Steps` checks of the condition have been done, or
+// 3. a sleep truncated by the cap on duration has been completed.
+// In case (1) the returned error is what the condition function returned.
+// In all other cases, ErrWaitTimeout is returned.
 func ExponentialBackoff(backoff Backoff, condition ConditionFunc) error {
 	for backoff.Steps > 0 {
 		if ok, err := condition(); err != nil || ok {