Polly: Improve Wait Policy Documentation

[LucaBlackDragon]

The WaitAndRetry policy (and similar ones) provides an overload allowing users to determine the sleep duration on runtime with a sleepDurationProvider function.
For instance:

//
// Summary:
//     Builds a Polly.Policy that will wait and retry retryCount times calling onRetry
//     on each retry with the raised exception, current sleep duration and context data.
//     On each retry, the duration to wait is calculated by calling sleepDurationProvider
//     with the current retry number (1 for first retry, 2 for second etc) and execution
//     context.
//
// Parameters:
//   policyBuilder:
//     The policy builder.
//
//   retryCount:
//     The retry count.
//
//   sleepDurationProvider:
//     The function that provides the duration to wait for for a particular retry attempt.
//
//   onRetry:
//     The action to call on each retry.
//
// Returns:
//     The policy instance.
//
// Exceptions:
//   T:System.ArgumentOutOfRangeException:
//     retryCount;Value must be greater than or equal to zero.
//
//   T:System.ArgumentNullException:
//     sleepDurationProvider or onRetry
public static RetryPolicy WaitAndRetry(this PolicyBuilder policyBuilder, int retryCount, Func<int, Context, TimeSpan> sleepDurationProvider, Action<Exception, TimeSpan, Context> onRetry);

The sleepDurationProvider function in this case is called with three parameters:

• an integer (which counts the attempts made at executing the code wrapped by the policy)
• a context object
• a timespan

Questions (unanswered by the documentation):

• Does the attempts counter start from 0 or 1?
• What is the meaning of the properties of the context object?
• What does the timespan value represent?

[m1nkeh]

I support this, in the fact that I also had to hunt around for the WaitAndRetry policy info, however.. with a bit of trial and error you can get there in the end 👍🏼.

The first thing to note is that the sleepDurationProvider is a Func(), and therefore the first two items are inputs, the third being an output.. this is not written in the documentation, as it is a C# concept.

In addition, there are some topics elsewhere on the Wiki, and although they are not _perhaps_ 100% complete.. they go in to some detail:

• Attempts: As you say, this goes in as the first param which is a counter of retry portion.. i would imagine that this starts from 1, that would seem logical as it wouldn't make sense for it to be a 0 attempt, but that is a guess...
• Context: Don't use it myself... but you can stick useful stuff about the 'state' of the retry i believe in it.. https://github.com/App-vNext/Polly/wiki/Keys-and-Context-Data
• Timespan: This is the length of time that will be waited.. this can be hard-coded or computed in the sleepDurationProvider.

Edit: Expanded response a wee bit 🤪.

[reisenberger]

Thanks @LucaBlackDragon ! Documentation added to the wiki page :+1: