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

app/logical/storage_manager.rb

@@ -1,8 +1,22 @@
+# StorageManager is an abstract superclass that defines a simple interface for
+# storing files on local or remote backends. All image files stored by Danbooru
+# are handled by a StorageManager.
+#
+# A StorageManager has methods for saving, deleting, and opening files, and for
+# generates URLs for images.
+#
+# @abstract
+# @see StorageManager::Local
+# @see StorageManager::SFTP
 class StorageManager
   class Error < StandardError; end
 
   attr_reader :base_url, :base_dir, :tagged_filenames
 
+  # Initialize a storage manager object.
+  # @param base_url [String] the base URL where images are stored (ex: "https://cdn.donmai.us/")
+  # @param base_dir [String] the base directory where images are stored (ex: "/var/www/danbooru/public/images")
+  # @param tagged_filenames [Boolean] whether image URLs can include tags
   def initialize(base_url:, base_dir:, tagged_filenames: Danbooru.config.enable_seo_post_urls)
     @base_url = base_url.chomp("/")
     @base_dir = base_dir
@@ -13,33 +27,57 @@ class StorageManager
   # location it should be overwritten atomically. Either the file is fully
   # written, or an error is raised and the original file is left unchanged. The
   # file should never be in a partially written state.
+  #
+  # @param io [IO] a file (or a readable IO object)
+  # @param path [String] the remote path where the file should be stored
   def store(io, path)
     raise NotImplementedError, "store not implemented"
   end
 
   # Delete the file at the given path. If the file doesn't exist, no error
   # should be raised.
+  # @param path [String] the remote path of the file to be deleted
   def delete(path)
     raise NotImplementedError, "delete not implemented"
   end
 
   # Return a readonly copy of the file located at the given path.
+  # @param path [String] the remote path of the file to open
+  # @return [MediaFile] the image file
   def open(path)
     raise NotImplementedError, "open not implemented"
   end
 
+  # Store or replace the given file belonging to the given post.
+  # @param io [IO] the file to store
+  # @param post [Post] the post the image belongs to
+  # @param type [Symbol] the image variant to store (:preview, :crop, :large, :original)
   def store_file(io, post, type)
     store(io, file_path(post.md5, post.file_ext, type))
   end
 
+  # Delete the file belonging to the given post.
+  # @param post_id [Integer] the post's id
+  # @param md5 [String] the post's md5
+  # @param file_ext [String] the post's file extension
+  # @param type [Symbol] the image variant to delete (:preview, :crop, :large, :original)
   def delete_file(post_id, md5, file_ext, type)
     delete(file_path(md5, file_ext, type))
   end
 
+  # Return a readonly copy of the image belonging to the given post.
+  # @param post [Post] the post
+  # @param type [Symbol] the image variant to open (:preview, :crop, :large, :original)
+  # @return [MediaFile] the image file
   def open_file(post, type)
     self.open(file_path(post.md5, post.file_ext, type))
   end
 
+  # Generate the image URL for the given post.
+  # @param post [Post] the post
+  # @param type [Symbol] the post's image variant (:preview, :crop, :large, :original)
+  # @param tagged_filename [Boolean] whether the URL should contain the post's tags
+  # @return [String] the image URL
   def file_url(post, type, tagged_filenames: false)
     subdir = subdir_for(post.md5)
     file = file_name(post.md5, post.file_ext, type)
@@ -100,6 +138,7 @@ class StorageManager
     "#{md5[0..1]}/#{md5[2..3]}/"
   end
 
+  # Generate the tags in the image URL.
   def seo_tags(post)
     return "" if !tagged_filenames