Change:
<!-- Please use this template while reporting a bug and provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner. Thanks! If the matter is security related, please disclose it privately via --What happened: While revising clients of I noticed that some comments there are misleading or confusing or incomplete. I am looking , which is in the latest commit in at the moment. The comment on the field named says it must be greater than or equal to zero. The comment does not call out any special meaning for zero. The method tolerates any value in the field, but treats zero irregularly (taking it to mean roughly the same thing as 1). The comments about all say that it is applied after , and give no other information. The method reveals that there is a broader and clearer thing to say. There is logic that determines the progression of values for , and at each step the jitter is to the returned value after the update (if any) to . The comment on says flatly that it is "The number of steps before duration stops changing". But this is not true; also stops changing once it hits . The comments on and should more clearly indicate that they are peers in determining when the increases in stop. The comment on says "The returned duration will never be greater than cap before jitter is applied", but this is not true in the method. When , is ignored. The comment on only says it is used to determine when to stop changing . The function interprets as a limit on the number of iterations (making its effect of limiting increases moot). The comment on the function says "It checks the condition up to Steps times" but this is not true. If the hits the earlier than that, the iteration is cut short.
/remove-sig architecture

Discussion:
type Backoff struct { // The initial duration. Duration time.Duration <del> // Duration is multiplied by factor each iteration. Must be greater // than or equal to zero. </del> <ins> // 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. </ins> Factor float64 <del> // The amount of jitter applied each iteration. Jitter is applied after // cap. </del> <ins> // The sleep at each iteration is the duration plus an additional // amount chosen uniformly at random from the interval between // zero and `jitter*duration`. </ins> Jitter float64 <del> // The number of steps before duration stops changing. If zero, initial // duration is always used. Used for exponential backoff in combination // with Factor. </del> <ins> // 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. </ins> Steps int <del> // The returned duration will never be greater than cap *before* jitter // is applied. The actual maximum cap is `cap * (1.0 + jitter)`. </del> <ins> // 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. </ins> Cap time.Duration } <del> // Step returns the next interval in the exponential backoff. This method // will mutate the provided backoff. </del> <ins> // 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. </ins> func (b *Backoff) Step() time.Duration { if b.Steps < 1 { if b.Jitter > 0 {

// ExponentialBackoff repeats a condition check with exponential backoff. // <del> // 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. </del> <ins> // 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. </ins> func ExponentialBackoff(backoff Backoff, condition ConditionFunc) error { for backoff.Steps > 0 { if ok, err := condition(); err != nil || ok {