Improve documentation for 'Control.Reaper' module in 'auto-update' package

[chshersh]

I want to use this library as a cache cleanup worker thread. But I have hard times understanding example in documentation. Specifically, those lines in Control.Reaper module:

, reaperAction = clean
, reaperDelay = 1000000 * 2 -- Clean every 2 second

-- Remove items > 10 seconds old
clean :: Cache -> IO (Cache -> Cache)

Why do you call action every 2 seconds to clean items outdated for more than 10 seconds? Why not just call this action once per 10 seconds?

Also, documentation for reaperAction is not clear enough.

reaperAction :: ReaperSettings workload item -> workload -> IO (workload -> workload)

The action to perform on a workload. The result of this is a "workload modifying" function. 
In the common case of using lists, the result should be a difference list that prepends the 
remaining workload to the temporary workload. 
For help with setting up such an action, see mkListAction.

Default: do nothing with the workload, and then prepend it to the temporary workload. 
This is incredibly useless; you should definitely override this default.

It's not clear, what is temporary workload because this term wasn't introduced in this module. And because of that it's not clear from example why clean function returns union instead of just filtering the cache.

[snoyberg]

For the first question: consider a situation where a new thing is being created every 1 second. That would mean that after 10 seconds, 0 items need to be reaped, and after 11 seconds, 1 needs to be reaped. If we waited every 10 seconds to reap, we would acquire 10 items to reap. Reaping every 2 seconds allows us to clean up those items more frequently.

The temporary workload here refers to items added to the workload while the reaper action is running. Clarifying that in the docs would definitely be a good thing, would you consider sending a doc PR?