Document clearly the recover method matching algorithm

[davidmichaelkarr]

Reading the documentation, it seems to me it would be helpful if the matching algorithm for determining a corresponding Recover method was explicitly spelled out. From what I can tell, it ONLY looks at the exception type. It's easy for someone to assume that since the recover method should (can?) have parameters matching the retryable method, that those would be used as part of the matching algorithm.

For instance, if a class has multiple retryable methods, more than one of which can fail with the same exception type, but with a different set of parameters, someone might write multiple recover methods that take the same exception type, but with different additional parameters.

This might even work in some situations, depending accidentally on how the algorithm picks the first method with the matching exception type. In other situations, someone would run into a weird exception deep in the retry mechanism, trying to copy a set of actual parameters to a set of variables whose type (or number) doesn't match.

However, now that I've pointed out the mistake that someone could make, I think it might also be useful to consider extending the matching algorithm to include the number and type of parameters. I know the parameters are optional, but I would think most people would be taking advantage of that.

At a minimum, the existing matching algorithm should be clearly documented.