safe_memoize 0.9.0 → 1.0.0

data/lib/safe_memoize/class_methods.rb

@@ -1,7 +1,43 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Class-level DSL added to any class that does +prepend SafeMemoize+.
   module ClassMethods
+    # Wraps an existing instance method with a thread-safe per-instance cache.
+    #
+    # Must be called *after* the method is defined. Raises +ArgumentError+ immediately
+    # at class-definition time if no such method exists.
+    #
+    # @param method_name [Symbol, String] name of the instance method to memoize
+    # @param ttl [Numeric, nil] seconds until the cached value expires; +nil+ means
+    #   the entry never expires. Falls back to {Configuration#default_ttl} when +nil+.
+    # @param max_size [Integer, nil] maximum number of cached entries per instance
+    #   for this method; the least-recently-used entry is evicted when the limit is
+    #   reached. Falls back to {Configuration#default_max_size} when +nil+.
+    # @param ttl_refresh [Boolean] when +true+, every cache *hit* resets the expiry
+    #   clock (sliding-window TTL). Requires +ttl:+ to be set.
+    # @param if [Proc, nil] callable predicate; the result is cached only when the
+    #   predicate returns truthy. Receives the computed return value as its argument.
+    # @param unless [Proc, nil] inverse of +:if+; the result is *not* cached when the
+    #   predicate returns truthy.
+    # @param shared [Boolean] when +true+, results are stored on the class rather than
+    #   per instance — all instances share one cache.
+    # @param key [Proc, nil] class-level custom cache key generator. Receives the same
+    #   arguments as the method and should return a single comparable value. Instance-level
+    #   keys set via {PublicCustomKeyMethods#memoize_with_custom_key} take priority.
+    # @return [void]
+    # @raise [ArgumentError] if the method does not exist, or option values are invalid
+    #
+    # @example Zero-argument method
+    #   def expensive_query = db.run("SELECT …")
+    #   memoize :expensive_query
+    #
+    # @example With TTL and LRU cap
+    #   def fetch(id) = http_get(id)
+    #   memoize :fetch, ttl: 60, max_size: 500
+    #
+    # @example Conditional — only cache successful responses
+    #   memoize :fetch, if: ->(v) { v[:status] == 200 }
     def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
       method_name = method_name.to_sym
 
@@ -196,6 +232,45 @@ module SafeMemoize
       prepend mod
     end
 
+    # Memoizes every eligible public instance method defined directly on the class.
+    #
+    # Accepts all options that {#memoize} accepts, plus +:except:+ and +:only:+.
+    # Raises +ArgumentError+ when both +:only:+ and +:except:+ are given.
+    #
+    # @param except [Array<Symbol, String>] method names to skip
+    # @param only [Array<Symbol, String>] when non-empty, only these methods are memoized
+    # @param include_protected [Boolean] also memoize +protected+ methods
+    # @param include_private [Boolean] also memoize +private+ methods
+    # @param options [Hash] any additional options forwarded to {#memoize}
+    # @return [void]
+    # @raise [ArgumentError] if both +:only:+ and +:except:+ are given
+    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
+      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
+
+      excluded = Array(except).map(&:to_sym)
+      included = Array(only).map(&:to_sym)
+
+      methods = public_instance_methods(false)
+      methods |= protected_instance_methods(false) if include_protected
+      methods |= private_instance_methods(false) if include_private
+
+      methods.each do |method_name|
+        next if excluded.include?(method_name)
+        next if included.any? && !included.include?(method_name)
+
+        memoize(method_name, **options)
+      end
+    end
+
+    # Clears one or all entries from the class-level shared cache.
+    #
+    # With no positional args after +method_name+, clears *all* shared entries for
+    # that method. With args/kwargs, clears only the matching entry.
+    #
+    # @param method_name [Symbol, String] the memoized method
+    # @param args [Array] positional arguments identifying the entry to clear
+    # @param kwargs [Hash] keyword arguments identifying the entry to clear
+    # @return [void]
     def reset_shared_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs]
@@ -211,6 +286,8 @@ module SafeMemoize
       end
     end
 
+    # Clears the entire class-level shared cache for this class.
+    # @return [void]
     def reset_all_shared_memos
       __safe_memo_shared_mutex__.synchronize do
         @__safe_memo_shared_cache__ = {}
@@ -218,6 +295,12 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if a live shared cache entry exists for the given call signature.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments
+    # @param kwargs [Hash] keyword arguments
+    # @return [Boolean]
     def shared_memoized?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -233,6 +316,11 @@ module SafeMemoize
       end
     end
 
+    # Returns the number of live entries in the class-level shared cache.
+    #
+    # @param method_name [Symbol, String, nil] when given, counts only entries for
+    #   that method; when +nil+, counts all methods.
+    # @return [Integer]
     def shared_memo_count(method_name = nil)
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__ || {}
@@ -242,6 +330,13 @@ module SafeMemoize
       end
     end
 
+    # Returns how many seconds ago the shared entry was cached, or +nil+ if not cached
+    # or already expired.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float, nil]
     def shared_memo_age(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -263,6 +358,12 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if the shared entry exists but its TTL has elapsed.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
     def shared_memo_stale?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -281,24 +382,6 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
-      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
-
-      excluded = Array(except).map(&:to_sym)
-      included = Array(only).map(&:to_sym)
-
-      methods = public_instance_methods(false)
-      methods |= protected_instance_methods(false) if include_protected
-      methods |= private_instance_methods(false) if include_private
-
-      methods.each do |method_name|
-        next if excluded.include?(method_name)
-        next if included.any? && !included.include?(method_name)
-
-        memoize(method_name, **options)
-      end
-    end
-
     private
 
     def __safe_memo_shared_cache__

data/lib/safe_memoize/configuration.rb

@@ -1,10 +1,48 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Global configuration for SafeMemoize.
+  #
+  # Obtain an instance via {SafeMemoize.configure} or {SafeMemoize.configuration}.
+  #
+  # @example
+  #   SafeMemoize.configure do |c|
+  #     c.default_ttl = 300
+  #     c.default_max_size = 100
+  #     c.on_hook_error = ->(err, type, key) { Bugsnag.notify(err) }
+  #   end
   class Configuration
-    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error,
-      :active_support_notifications, :statsd_client, :opentelemetry_tracer
+    # @return [Numeric, nil] Default TTL (seconds) applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +ttl:+. +nil+ means no expiry.
+    attr_accessor :default_ttl
 
+    # @return [Integer, nil] Default LRU size cap applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +max_size:+. +nil+ means unlimited.
+    attr_accessor :default_max_size
+
+    # @return [Proc, nil] Custom handler for deprecation warnings.
+    #   Receives a single +String+ message. When +nil+, warnings are written to +$stderr+.
+    attr_accessor :on_deprecation
+
+    # @return [Proc, nil] Custom handler for errors raised inside lifecycle hooks.
+    #   Receives +(Exception, Symbol hook_type, cache_key)+. When +nil+, a warning is
+    #   written to +$stderr+ and the error is swallowed.
+    attr_accessor :on_hook_error
+
+    # @return [Boolean] When +true+, SafeMemoize emits +ActiveSupport::Notifications+
+    #   events for cache hits, misses, stores, evictions, and expirations.
+    #   Requires +activesupport+ to be loaded; has zero overhead when it is not.
+    attr_accessor :active_support_notifications
+
+    # @return [Object, nil] Any StatsD-compatible client (responds to +#increment+).
+    #   When set, {Adapters::StatsD} routes lifecycle events to this client.
+    attr_accessor :statsd_client
+
+    # @return [Object, nil] An OpenTelemetry tracer (responds to +#in_span+).
+    #   When set, {Adapters::OpenTelemetry} wraps each cache-miss computation in a span.
+    attr_accessor :opentelemetry_tracer
+
+    # @api private
     def initialize
       @default_ttl = nil
       @default_max_size = nil

data/lib/safe_memoize/custom_key_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CustomKeyMethods
     private
 

data/lib/safe_memoize/hooks_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module HooksMethods
     NOTIFICATION_EVENT_NAMES = {
       on_hit: "cache_hit.safe_memoize",

data/lib/safe_memoize/inspection_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module InspectionMethods
     private
 
@@ -14,7 +15,7 @@ module SafeMemoize
       if args.empty? && kwargs.empty?
         ->(key) { key[0] == method_name }
       else
-        cache_key = safe_memo_cache_key(method_name, args, kwargs)
+        cache_key = compute_cache_key(method_name, args, kwargs)
         ->(key) { key == cache_key }
       end
     end

data/lib/safe_memoize/instance_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module InstanceMethods
     include PublicMethods
     include CacheStoreMethods

data/lib/safe_memoize/lru_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module LruMethods
     private
 

data/lib/safe_memoize/public_custom_key_methods.rb

@@ -1,13 +1,36 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Instance-level custom cache key registration.
   module PublicCustomKeyMethods
+    # Registers a per-instance custom key generator for a memoized method.
+    #
+    # The block receives the same arguments as the method and should return a
+    # single value used as the cache key. Two calls that produce the same key
+    # value share one cached result, regardless of their raw arguments.
+    #
+    # Instance-level keys take priority over the class-level +key:+ option set
+    # in {ClassMethods#memoize}.
+    #
+    # @param method_name [Symbol, String]
+    # @yield [*args, **kwargs] called with the method's arguments on each invocation
+    # @yieldreturn [Object] the key value (must be comparable with +==+)
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example Collapse all option hashes that share the same user ID
+    #   obj.memoize_with_custom_key(:fetch) { |user_id, _options| user_id }
     def memoize_with_custom_key(method_name, &key_generator)
       raise ArgumentError, "block required for key generation" unless key_generator
 
       register_custom_key(method_name, &key_generator)
     end
 
+    # Removes the custom key generator for one method, or all generators.
+    #
+    # @param method_name [Symbol, String, nil] when given, removes only that method's
+    #   generator; when +nil+, removes all generators on this instance
+    # @return [void]
     def clear_custom_keys(method_name = nil)
       if method_name
         with_memo_lock do

data/lib/safe_memoize/public_methods.rb

@@ -1,19 +1,36 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Public instance methods mixed into every class that prepends {SafeMemoize}.
   module PublicMethods
+    # Returns +true+ if the given call is currently cached (and not expired).
+    #
+    # Always returns +false+ when a block is provided, because block-taking methods
+    # cannot be safely keyed by arguments alone.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments used to look up the entry
+    # @param kwargs [Hash] keyword arguments used to look up the entry
+    # @return [Boolean]
     def memoized?(method_name, *args, **kwargs, &block)
       return false if block
 
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         memo_cache_hit?(cache_key)
       end
     end
 
+    # Returns the number of seconds until the cached entry expires.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float] seconds remaining (may be 0 if already expired)
+    # @return [nil] if the entry has no TTL or is not cached
     def memo_ttl_remaining(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         record = memo_cache_record(cache_key)
@@ -27,6 +44,10 @@ module SafeMemoize
       end
     end
 
+    # Returns the number of live cached entries for a method (or all methods).
+    #
+    # @param method_name [Symbol, String, nil] when omitted, counts all methods
+    # @return [Integer]
     def memo_count(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -35,6 +56,13 @@ module SafeMemoize
       end
     end
 
+    # Returns metadata hashes describing each cached entry.
+    #
+    # Each hash contains +:args+, +:kwargs+ (or +:custom_key+ for custom-keyed entries),
+    # and +:method+ when no +method_name+ filter is applied.
+    #
+    # @param method_name [Symbol, String, nil] when omitted, returns entries for all methods
+    # @return [Array<Hash>]
     def memo_keys(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -43,6 +71,12 @@ module SafeMemoize
       end
     end
 
+    # Returns metadata hashes including the cached value for each entry.
+    #
+    # Each hash contains all fields from {#memo_keys} plus +:value+.
+    #
+    # @param method_name [Symbol, String, nil] when omitted, returns entries for all methods
+    # @return [Array<Hash>]
     def memo_values(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -51,42 +85,90 @@ module SafeMemoize
       end
     end
 
+    # Registers a hook that fires on every cache hit.
+    #
+    # @yield [cache_key, record] called synchronously inside the cache lock
+    # @yieldparam cache_key [Array] the internal cache key
+    # @yieldparam record [Hash] the cache record (+:value+, +:expires_at+, +:cached_at+)
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_expire(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_expire, &block)
     end
 
+    # Registers a hook that fires when an LRU eviction occurs.
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_evict(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_evict, &block)
     end
 
+    # Registers a hook that fires on every cache hit.
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_hit(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_hit, &block)
     end
 
+    # Registers a hook that fires on every cache miss (before the value is stored).
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_miss(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_miss, &block)
     end
 
+    # Registers a hook that fires whenever a value is written to the cache
+    # (miss, {#warm_memo}, or {#load_memo}).
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_store(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_store, &block)
     end
 
+    # Removes all registered hooks, or only hooks of a specific type.
+    #
+    # @param hook_type [Symbol, nil] one of +:on_hit+, +:on_miss+, +:on_store+,
+    #   +:on_expire+, +:on_evict+; when +nil+ all hooks are cleared
+    # @return [void]
     def clear_memo_hooks(hook_type = nil)
       with_memo_lock do
         _clear_memo_hooks(hook_type)
       end
     end
 
+    # Pre-populates a cache entry with the value returned by the block without
+    # calling the memoized method itself.
+    #
+    # Useful for warming caches from a serialized snapshot or an external source.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments that identify the cache slot
+    # @param ttl [Numeric, nil] optional expiry for the warmed entry
+    # @param kwargs [Hash] keyword arguments that identify the cache slot
+    # @yield [] must return the value to store
+    # @return [Object] the value returned by the block
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example
+    #   obj.warm_memo(:find, 42) { User.new(id: 42, name: "cached") }
     def warm_memo(method_name, *args, ttl: nil, **kwargs, &block)
       raise ArgumentError, "block required" unless block
 
@@ -104,6 +186,17 @@ module SafeMemoize
       value
     end
 
+    # Calls the memoized method for each argument set and caches all results.
+    #
+    # Equivalent to calling the method for each arg set individually, but expressed
+    # as a single call for clarity.
+    #
+    # @param method_name [Symbol, String]
+    # @param arg_sets [Array<Array>] each element is an argument list for one call
+    # @return [Array] cached values in input order
+    #
+    # @example
+    #   obj.memo_preload(:find, [1], [2], [3])
     def memo_preload(method_name, *arg_sets)
       method_name = method_name.to_sym
       arg_sets.map do |args|
@@ -111,6 +204,11 @@ module SafeMemoize
       end
     end
 
+    # Exports live cache entries as a plain hash suitable for serialization.
+    #
+    # @param method_name [Symbol, String, nil] when given, exports only entries for
+    #   that method; when +nil+, exports all methods
+    # @return [Hash] mapping cache keys to their cached values (expired entries excluded)
     def dump_memo(method_name = nil)
       method_name = method_name&.to_sym
 
@@ -122,6 +220,14 @@ module SafeMemoize
       end
     end
 
+    # Restores cache entries from a snapshot produced by {#dump_memo}.
+    #
+    # Existing entries are not cleared; snapshot keys are merged in.
+    # Each restored entry fires the +:on_store+ hook.
+    #
+    # @param snapshot [Hash] a hash previously returned by {#dump_memo}
+    # @return [nil]
+    # @raise [ArgumentError] if +snapshot+ is not a +Hash+
     def load_memo(snapshot)
       raise ArgumentError, "snapshot must be a Hash" unless snapshot.is_a?(Hash)
 
@@ -137,9 +243,17 @@ module SafeMemoize
       nil
     end
 
+    # Resets the expiry clock on a live cached entry without recomputing its value.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param ttl [Numeric, nil] new TTL to apply; when +nil+, uses the original TTL
+    #   derived from the entry's +cached_at+ and +expires_at+ timestamps
+    # @param kwargs [Hash]
+    # @return [Boolean] +true+ if the entry existed and was touched; +false+ otherwise
     def memo_touch(method_name, *args, ttl: nil, **kwargs)
       method_name = method_name.to_sym
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         cache = memo_cache_or_nil
@@ -162,14 +276,27 @@ module SafeMemoize
       end
     end
 
+    # Clears the cached entry and immediately re-calls the method to populate a
+    # fresh value.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Object] the freshly computed and cached value
     def memo_refresh(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       reset_memo(method_name, *args, **kwargs)
       send(method_name, *args, **kwargs)
     end
 
+    # Returns how many seconds ago the entry was cached, or +nil+ if not cached.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float, nil]
     def memo_age(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         record = memo_cache_record(cache_key)
@@ -182,8 +309,14 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if the entry exists but its TTL has elapsed.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
     def memo_stale?(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         cache = memo_cache_or_nil
@@ -196,6 +329,16 @@ module SafeMemoize
       end
     end
 
+    # Removes one or all cached entries for a method.
+    #
+    # When called with only +method_name+, all entries for that method are cleared.
+    # When called with +method_name+ *and* arguments, only the exact matching entry
+    # is cleared. Each evicted entry fires the +:on_evict+ hook.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments identifying a specific entry
+    # @param kwargs [Hash] keyword arguments identifying a specific entry
+    # @return [void]
     def reset_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
 
@@ -215,6 +358,10 @@ module SafeMemoize
       end
     end
 
+    # Clears all cached entries for every method on this instance.
+    # Each evicted entry fires the +:on_evict+ hook.
+    #
+    # @return [void]
     def reset_all_memos
       with_memo_lock do
         if defined?(@__safe_memo_cache__) && @__safe_memo_cache__
@@ -227,6 +374,16 @@ module SafeMemoize
       end
     end
 
+    # Returns a detailed snapshot of a single cached entry, or +nil+ if not cached.
+    #
+    # All reads are performed inside a single mutex hold.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Hash, nil] hash with keys +:cached+, +:value+, +:hits+, +:misses+,
+    #   +:ttl_remaining+, +:age+, +:custom_key+, +:lru_position+; or +nil+ when
+    #   the entry is not present
     def memo_inspect(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = compute_cache_key(method_name, args, kwargs)

data/lib/safe_memoize/public_metrics_methods.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Per-instance cache metrics: hit/miss counts and average computation time.
   module PublicMetricsMethods
+    # Returns aggregate metrics across all memoized methods on this instance.
+    #
+    # @return [Hash] with keys +:total_hits+, +:total_misses+, +:hit_rate+,
+    #   +:miss_rate+, +:average_computation_time+, and +:entries+ (one entry
+    #   per cached argument combination)
     def cache_stats
       with_memo_lock do
         metrics = memo_metrics_store
@@ -11,6 +17,11 @@ module SafeMemoize
       end
     end
 
+    # Returns metrics for a single memoized method.
+    #
+    # @param method_name [Symbol, String]
+    # @return [Hash] same shape as {#cache_stats} but scoped to one method,
+    #   with an extra +:method+ key
     def cache_stats_for(method_name)
       method_name = method_name.to_sym
 
@@ -22,14 +33,23 @@ module SafeMemoize
       end
     end
 
+    # Returns the overall cache hit rate as a percentage (0.0–100.0).
+    # @return [Float]
     def cache_hit_rate
       cache_stats[:hit_rate]
     end
 
+    # Returns the overall cache miss rate as a percentage (0.0–100.0).
+    # @return [Float]
     def cache_miss_rate
       cache_stats[:miss_rate]
     end
 
+    # Resets hit/miss counters, either for one method or for all methods.
+    #
+    # @param method_name [Symbol, String, nil] when given, resets only that method's
+    #   metrics; when +nil+, resets all
+    # @return [void]
     def cache_metrics_reset(method_name = nil)
       with_memo_lock do
         if method_name

data/lib/safe_memoize/rails/middleware.rb

@@ -13,6 +13,8 @@ module SafeMemoize
         @app = app
       end
 
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triplet
       def call(env)
         @app.call(env)
       ensure