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

app/logical/session_loader.rb

@@ -1,14 +1,27 @@
+# Loads the current user from their session cookies or API key. Used by the
+# ApplicationController to set the CurrentUser global early during the HTTP
+# request cycle.
+#
+# @see ApplicationController#set_current_user
+# @see CurrentUser
 class SessionLoader
   class AuthenticationFailure < StandardError; end
 
   attr_reader :session, :request, :params
 
+  # Initialize the session loader.
+  # @param request the HTTP request
   def initialize(request)
     @request = request
     @session = request.session
     @params = request.parameters
   end
 
+  # Attempt to log a user in with the given username and password. Records a
+  # login attempt event and returns the user if successful.
+  # @param name [String] the username
+  # @param password [String] the user's password
+  # @return [User, nil] the user if the password was correct, otherwise nil
   def login(name, password)
     user = User.find_by_name(name)
 
@@ -30,6 +43,7 @@ class SessionLoader
     end
   end
 
+  # Logs the current user out. Deletes their session cookie and records a logout event.
   def logout
     session.delete(:user_id)
     session.delete(:last_authenticated_at)
@@ -37,6 +51,17 @@ class SessionLoader
     UserEvent.create_from_request!(CurrentUser.user, :logout, request)
   end
 
+  # Sets the current user. Runs on each HTTP request. The user is set based on
+  # their API key, their session cookie, or the signed user id param (used when
+  # reseting a password from an magic email link)
+  #
+  # Also performs post-load actions, including updating the user's last login
+  # timestamp, their last used IP, their timezone, their database timeout, their
+  # country, whether safe mode is enabled, their session cookie, and unbanning
+  # banned users if their ban is expired.
+  #
+  # @see ApplicationController#set_current_user
+  # @see CurrentUser
   def load
     CurrentUser.user = User.anonymous
     CurrentUser.ip_addr = request.remote_ip
@@ -61,6 +86,7 @@ class SessionLoader
     DanbooruLogger.add_session_attributes(request, session, CurrentUser.user)
   end
 
+  # @return [Boolean] true if the current request has an API key
   def has_api_authentication?
     request.authorization.present? || params[:login].present? || (params[:api_key].present? && params[:api_key].is_a?(String))
   end
@@ -72,6 +98,8 @@ class SessionLoader
     ActiveRecord::Base.connection.execute("set statement_timeout = #{timeout}")
   end
 
+  # Sets the current API user based on either the `login` + `api_key` URL params,
+  # or HTTP Basic Auth.
   def load_session_for_api
     if request.authorization
       authenticate_basic_auth
@@ -82,6 +110,7 @@ class SessionLoader
     end
   end
 
+  # Sets the current API user based on the HTTP Basic Auth params.
   def authenticate_basic_auth
     credentials = ::Base64.decode64(request.authorization.split(' ', 2).last || '')
     login, api_key = credentials.split(/:/, 2)
@@ -89,6 +118,12 @@ class SessionLoader
     authenticate_api_key(login, api_key)
   end
 
+  # Sets the current user if their API key is valid.
+  # @param name [String] the user name
+  # @param key [String] the API key
+  # @raise AuthenticationFailure if the API key is invalid
+  # @raise User::PrivilegeError if the API key doesn't have the required
+  #   permissions for this endpoint
   def authenticate_api_key(name, key)
     user, api_key = User.find_by_name(name)&.authenticate_api_key(key)
     raise AuthenticationFailure if user.blank?
@@ -97,12 +132,14 @@ class SessionLoader
     CurrentUser.user = user
   end
 
+  # Set the current user based on the `signed_user_id` URL param. This param is used by the reset password email.
   # XXX use rails 6.1 signed ids (https://github.com/rails/rails/blob/6-1-stable/activerecord/CHANGELOG.md)
   def load_param_user(signed_user_id)
     session[:user_id] = Danbooru::MessageVerifier.new(:login).verify(signed_user_id)
     load_session_user
   end
 
+  # Set the current user based on the `user_id` session cookie.
   def load_session_user
     user = User.find_by_id(session[:user_id])
     CurrentUser.user = user if user