Improve docs

CHANGELOG.md

@@ -1,6 +1,6 @@
 - Make sure Bucket#able_to_accept? allows the bucket to be filled to capacity, not only to below capacity
 - Improve YARD documentation
-- Allow "conditional fillup" - only add tokens to the leaky bucket if the bucket has enough space
+- Allow "conditional fillup" - only add tokens to the leaky bucket if the bucket has enough space.
 - Fix `over_time` leading to incorrect `leak_rate`. The divider/divisor were swapped, leading to the inverse leak rate getting computed.
 
 ## [0.3.0] - 2024-01-18

README.md

@@ -67,6 +67,8 @@ throttle.request!(20) # Attempt to withdraw 20 dollars more
 throttle.request!(2) # Attempt to withdraw 2 dollars more, will raise `Throttled` and block withdrawals for 3 hours
 ```
 
+## Using just the leaky bucket
+
 Sometimes you don't want to use a throttle, but you want to track the amount added to the leaky bucket over time. A lower-level abstraction is available for that purpose in the form of the `LeakyBucket` class. It will not raise any exceptions and will not install blocks, but will permit you to track a bucket's state over time:
 
 
@@ -77,7 +79,8 @@ sleep 0.2
 b.state #=> Pecorino::LeakyBucket::State(full?: false, level: 1.8)
 ```
 
-Check out the inline YARD documentation for more options.
+Check out the inline YARD documentation for more options. Do take note of the differences between `fillup()` and `fillup_conditionally` as you
+might want to pick one or the other depending on your use case.
 
 ## Cleaning out stale locks from the database
 

lib/pecorino/leaky_bucket.rb

@@ -102,7 +102,8 @@ def initialize(key:, capacity:, leak_rate: nil, over_time: nil)
   end
 
   # Places `n` tokens in the bucket. If the bucket has less capacity than `n` tokens, the bucket will be filled to capacity.
-  # If the bucket has less capacity than `n` tokens, it will be filled to capacity.
+  # If the bucket has less capacity than `n` tokens, it will be filled to capacity. If the bucket is already full
+  # when the fillup is requested, the bucket stays at capacity.
   #
   # Once tokens are placed, the bucket is set to expire within 2 times the time it would take it to leak to 0,
   # regardless of how many tokens get put in - since the amount of tokens put in the bucket will always be capped
@@ -115,10 +116,9 @@ def fillup(n_tokens)
     State.new(capped_level_after_fillup, is_full)
   end
 
-  # Places `n` tokens in the bucket, but only if there actually is enough capacity left.
-
   # Places `n` tokens in the bucket. If the bucket has less capacity than `n` tokens, the fillup will be rejected.
-  # This can be used for "exactly once" semantics or just more precise rate limiting.
+  # This can be used for "exactly once" semantics or just more precise rate limiting. Note that if the bucket has
+  # _exactly_ `n` tokens of capacity the fillup will be accepted.
   #
   # Once tokens are placed, the bucket is set to expire within 2 times the time it would take it to leak to 0,
   # regardless of how many tokens get put in - since the amount of tokens put in the bucket will always be capped