docs: add remaining docs for classes in app/logical.

app/logical/rate_limiter.rb

@@ -1,3 +1,13 @@
+# A RateLimiter handles HTTP rate limits for controller actions. Rate limits are
+# based on the user, the user's IP, and the controller action.
+#
+# A RateLimiter is backed by RateLimit objects stored in the database, which
+# track the rate limits with a token bucket algorithm. A RateLimiter object
+# usually has two RateLimits, one for the current user and one for their IP.
+#
+# @see RateLimit
+# @see ApplicationController#check_rate_limit
+# @see https://en.wikipedia.org/wiki/Token_bucket
 class RateLimiter
   class RateLimitError < StandardError; end
 
@@ -11,6 +21,15 @@ class RateLimiter
     @burst = burst
   end
 
+  # Create a RateLimiter object for the current controller, action, user, and
+  # IP. A RateLimiter usually has two RateLimits, one for the user and one for
+  # their IP. The action is limited if either the user or their IP are limited.
+  #
+  # @param controller_name [String] the current controller
+  # @param action_name [String] the current controller action
+  # @param user [User] the current user
+  # @param ip_addr [String] the user's IP address
+  # @return [RateLimit] the rate limit for the action
   def self.for_action(controller_name, action_name, user, ip_addr)
     action = "#{controller_name}:#{action_name}"
     keys = [(user.cache_key unless user.is_anonymous?), "ip/#{ip_addr.to_s}"].compact
@@ -33,10 +52,12 @@ class RateLimiter
     RateLimiter.new(action, keys, rate: rate, burst: burst)
   end
 
+  # @raise [RateLimitError] if the action is limited
   def limit!
     raise RateLimitError if limited?
   end
 
+  # @return [Boolean] true if the action is limited for the user or their IP
   def limited?
     rate_limits.any?(&:limited?)
   end
@@ -46,6 +67,7 @@ class RateLimiter
     super(options).except("keys", "rate_limits").merge(limits: hash)
   end
 
+  # Update or create the rate limits associated with this action.
   def rate_limits
     @rate_limits ||= RateLimit.create_or_update!(action: action, keys: keys, cost: cost, rate: rate, burst: burst)
   end