Improve documentation with timelines, examples

[t3hmrman]

Thanks to rnottaken on Reddit for noting the lack of clarity in the documentation around the API, for example differences/distinction between check_interval and cooldown.

Conversation reproduced below:

Hey first of, nice crate!

I get what you're doing, but I think that the docs would be easier understandable with more examples of usage.

https://docs.rs/situwaition/0.2.1/situwaition/struct.SituwaitionOpts.html# for instance, it was hard for me to decipher what the timeline would be if I specify both the interval and the cooldown. When will the checks happen? When is the first going to happen and when will the next one happen? Is the first check going to happen after interval and every other after cooldown? Is interval the right choice of word then?

I responded with:

Hey thanks for the comment -- I appreciate you taking a look!

Yeah, it is a bit confusing, let me try and lay it out.

So interval actually has to do with checking for completion, where as cooldown happens after doing the actual action (it's a throttle, really, maybe I should rename it!)... Maybe it should be called backoff.

This was a result of realizing that how often you check and how often you run the function are separate "timelines" so to speak.

If I try and think of an example:

• check takes 100ms
• check interval is 500ms
• timeout is 1000ms

In this scenario, the check will run 10 times, and you'll check once (the second check will likely be past 1000ms in the future)

Maybe the check is something we don't want to run 10 times a second -- maybe it should only be run every half a second at most -- this means that we need to stop the check from running, but we might want to keep checking so we can exit early as fast as possible.

In that case you would want:

• check takes 100ms (the operation hasn't changed)
• cooldown is 400ms
• check interval is 100ms (we want to find out as fast as possible that it's done, around)
• timeout is 1000ms

In this scenario, we've slowed down the checks (so we're not doing them as fast as possible), but the interval at which we check whether

This 100% needs some more thinking on my part -- a diagram and examples, so I'm going to file an issue -- thanks again for bringing this up.

To improve the documentation the following should be done:

• Think about and write a FAQ section on the distinction between cooldown and check_interval
• Consider renaming cooldown to backoff (BackoffStrategy might be a good enum to create)
• Add example timeline visualizations
• Add non-trivial usage examples (ex. using reqwest) early in the documentation.
• Make the per-runtime/implementation sections more succinct if possible.

[t3hmrman]

More thoughts from reddit:

The big one I've seen is in tests, particularly of code where something happens in the background, and your tests have a pattern of "do X, wait for spawned task to complete, check Y". If you have a hardcoded wait it's either too short (so your tests are flaky) or too long (so your tests are slow), and something like situwaition works really well to let you wait exactly until the condition you're waiting for is true.