Improve docs

README.md

@@ -58,7 +58,7 @@ return render :capacity_exceeded unless throttle.able_to_accept?
 If you are dealing with a metered resource (like throughput, money, amount of storage...) you can supply the number of tokens to either `request!` or `able_to_accept?` to indicate the desired top-up of the leaky bucket. For example, if you are maintaining user wallets and want to ensure no more than 100 dollars may be taken from the wallet within a certain amount of time, you can do it like so:
 
 ```ruby
-throttle = Pecorino::Throttle.new(key: "wallet_t_#{current_user.id}", leak_rate: 100 / 60.0 / 60.0, capacity: 100, block_for: 60*60*3)
+throttle = Pecorino::Throttle.new(key: "wallet_t_#{current_user.id}", over_time_: 1.hour, capacity: 100, block_for: 60*60*3)
 throttle.request!(20) # Attempt to withdraw 20 dollars
 throttle.request!(20) # Attempt to withdraw 20 dollars more
 throttle.request!(20) # Attempt to withdraw 20 dollars more

lib/pecorino/leaky_bucket.rb

@@ -77,9 +77,12 @@ def to_i
   # @param key[String] the key for the bucket. The key also gets used
   #   to derive locking keys, so that operations on a particular bucket
   #   are always serialized.
-  # @param leak_rate[Float] the leak rate of the bucket, in tokens per second
-  # @param over_time[Float] over how long the bucket will leak out.
-  #   Either of `leak_rate` or `over_time` can be used
+  # @param leak_rate[Float] the leak rate of the bucket, in tokens per second.
+  #   Either `leak_rate` or `over_time` can be used, but not both. 
+  # @param over_time[#to_f] over how many seconds the bucket will leak out to 0 tokens.
+  #   The value is assumed to be the number of seconds
+  #   - or a duration which returns the number of seconds from `to_f`.
+  #   Either `leak_rate` or `over_time` can be used, but not both. 
   # @param capacity[Numeric] how many tokens is the bucket capped at.
   #   Filling up the bucket using `fillup()` will add to that number, but
   #   the bucket contents will then be capped at this value. So with