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.

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
+	// Duration is multiplied by factor each iteration, if factor is not zero
-	// than or equal to 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
+	// The sleep at each iteration is the duration plus an additional
-	// cap.
+	// 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
+	// The remaining number of iterations in which the duration
-	// duration is always used. Used for exponential backoff in combination
+	// parameter may change (but progress can be stopped earlier by
-	// with Factor.
+	// 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
+	// A limit on revised values of the duration parameter. If a
-	// is applied. The actual maximum cap is `cap * (1.0 + jitter)`.
+	// 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
+// Step (1) returns an amount of time to sleep determined by the
-// will mutate the provided backoff.
+// 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
+// It repeatedly checks the condition and then sleeps, using `backoff.Step()`
-// the previous duration by Factor.
+// to determine the length of the sleep and adjust Duration and Steps.
-//
+// Stops and returns as soon as:
-// If Jitter is greater than zero, a random amount of each duration is added
+// 1. the condition check returns true or an error,
-// (between duration and duration*(1+jitter)).
+// 2. `backoff.Steps` checks of the condition have been done, or
-//
+// 3. a sleep truncated by the cap on duration has been completed.
-// If the condition never returns true, ErrWaitTimeout is returned. All other
+// In case (1) the returned error is what the condition function returned.
-// errors terminate immediately.
+// 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 {