From ad4c75eb1a66aa8e7abe3c64a37c49529aa9bb4d Mon Sep 17 00:00:00 2001
From: evazion <noizave@gmail.com>
Date: Sun, 27 Jun 2021 18:12:58 -0500
Subject: [PATCH] docs add more docs to app/{jobs,logical}.

These were missed in the last commit.
---
 app/controllers/README.md                    | 2 +-
 app/jobs/bigquery_export_job.rb              | 4 ++++
 app/jobs/discord_notification_job.rb         | 2 ++
 app/jobs/iqdb_add_post_job.rb                | 2 ++
 app/jobs/iqdb_remove_post_job.rb             | 2 ++
 app/jobs/populate_saved_search_job.rb        | 2 ++
 app/jobs/process_tag_relationship_job.rb     | 3 +++
 app/jobs/tag_batch_change_job.rb             | 2 +-
 app/jobs/upload_service_delayed_start_job.rb | 2 +-
 app/logical/concerns/mentionable.rb          | 3 +++
 app/logical/danbooru/http/redirector.rb      | 4 ++--
 app/logical/storage_manager/local.rb         | 1 +
 app/logical/storage_manager/null.rb          | 2 ++
 app/mailers/application_mailer.rb            | 3 +++
 config/application.rb                        | 9 +++++----
 script/fixes/README.md                       | 4 ++--
 16 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/app/controllers/README.md b/app/controllers/README.md
index cdecd2c61..9df0e3380 100644
--- a/app/controllers/README.md
+++ b/app/controllers/README.md
@@ -73,7 +73,7 @@ Each controller action above corresponds to an URL:
 | BansController#update  | PUT https://danbooru.donmai.us/bans/1234    | PUT /bans/:id       |                     |                               |
 | BansController#destroy | DELETE https://danbooru.donmai.us/bans/1234 | DELETE /bans/:id    |                     |                               |
 
-These routes are defined in [config/routes.rb](../config/routes.rb).
+These routes are defined in [config/routes.rb](../../config/routes.rb).
 
 # Authorization
 
diff --git a/app/jobs/bigquery_export_job.rb b/app/jobs/bigquery_export_job.rb
index 007eea8fd..8e458b49c 100644
--- a/app/jobs/bigquery_export_job.rb
+++ b/app/jobs/bigquery_export_job.rb
@@ -1,3 +1,7 @@
+# A job that exports a database table to Google Cloud Storage and to Google
+# BigQuery. Spawned daily by {DanbooruMaintenance}.
+#
+# @see BigqueryExportService
 class BigqueryExportJob < ApplicationJob
   retry_on Exception, attempts: 0
 
diff --git a/app/jobs/discord_notification_job.rb b/app/jobs/discord_notification_job.rb
index 20251c178..4f17a2191 100644
--- a/app/jobs/discord_notification_job.rb
+++ b/app/jobs/discord_notification_job.rb
@@ -1,3 +1,5 @@
+# A job that sends notifications about new forum posts to Discord. Spawned by
+# the {ForumPost} class when a new forum post is created.
 class DiscordNotificationJob < ApplicationJob
   retry_on Exception, attempts: 0
 
diff --git a/app/jobs/iqdb_add_post_job.rb b/app/jobs/iqdb_add_post_job.rb
index a99daa6f0..e94b61cd2 100644
--- a/app/jobs/iqdb_add_post_job.rb
+++ b/app/jobs/iqdb_add_post_job.rb
@@ -1,3 +1,5 @@
+# A job that adds a post to IQDB when a new post is uploaded, or when a post is
+# regenerated. Spawned by the {Post} class.
 class IqdbAddPostJob < ApplicationJob
   def perform(post)
     IqdbClient.new.add_post(post)
diff --git a/app/jobs/iqdb_remove_post_job.rb b/app/jobs/iqdb_remove_post_job.rb
index 3d4cda697..40832c79b 100644
--- a/app/jobs/iqdb_remove_post_job.rb
+++ b/app/jobs/iqdb_remove_post_job.rb
@@ -1,3 +1,5 @@
+# A job that removes a post from IQDB when it is deleted. Spawned by the {Post}
+# class.
 class IqdbRemovePostJob < ApplicationJob
   def perform(post_id)
     IqdbClient.new.remove(post_id)
diff --git a/app/jobs/populate_saved_search_job.rb b/app/jobs/populate_saved_search_job.rb
index 81b34c8d8..a67681d69 100644
--- a/app/jobs/populate_saved_search_job.rb
+++ b/app/jobs/populate_saved_search_job.rb
@@ -1,3 +1,5 @@
+# A job that updates a user's saved searches when they do a search for
+# `search:all` or `search:<label>`.
 class PopulateSavedSearchJob < ApplicationJob
   queue_as :default
 
diff --git a/app/jobs/process_tag_relationship_job.rb b/app/jobs/process_tag_relationship_job.rb
index 14940c6d6..78f9b4590 100644
--- a/app/jobs/process_tag_relationship_job.rb
+++ b/app/jobs/process_tag_relationship_job.rb
@@ -1,3 +1,6 @@
+# A job that processes a single tag alias or implication when a bulk update
+# request is approved. One job per alias or implication is spawned. Jobs are
+# processed sequentially in the `bulk_update` queue.
 class ProcessTagRelationshipJob < ApplicationJob
   queue_as :bulk_update
   retry_on Exception, attempts: 0
diff --git a/app/jobs/tag_batch_change_job.rb b/app/jobs/tag_batch_change_job.rb
index 85fa9c4ef..f04aa4254 100644
--- a/app/jobs/tag_batch_change_job.rb
+++ b/app/jobs/tag_batch_change_job.rb
@@ -1,5 +1,5 @@
 # A job that performs a mass update or tag nuke operation in a bulk update
-# request.
+# request. Jobs in the `bulk_update` queue are processed sequentially.
 class TagBatchChangeJob < ApplicationJob
   queue_as :bulk_update
 
diff --git a/app/jobs/upload_service_delayed_start_job.rb b/app/jobs/upload_service_delayed_start_job.rb
index afedce129..45c65663f 100644
--- a/app/jobs/upload_service_delayed_start_job.rb
+++ b/app/jobs/upload_service_delayed_start_job.rb
@@ -1,4 +1,4 @@
-# A job that tries to resume a preprocessed image upload.
+# A job that tries to resume a preprocessed image upload job.
 class UploadServiceDelayedStartJob < ApplicationJob
   queue_as :default
   queue_with_priority(-1)
diff --git a/app/logical/concerns/mentionable.rb b/app/logical/concerns/mentionable.rb
index 71522378e..e61b29cd7 100644
--- a/app/logical/concerns/mentionable.rb
+++ b/app/logical/concerns/mentionable.rb
@@ -1,3 +1,6 @@
+# A concern that handles @mentions in comments and forum posts. Sends a DMail
+# to mentioned users when a comment or forum post is created or edited to add
+# new mentions.
 module Mentionable
   extend ActiveSupport::Concern
 
diff --git a/app/logical/danbooru/http/redirector.rb b/app/logical/danbooru/http/redirector.rb
index 388dd3d58..6bb992ee2 100644
--- a/app/logical/danbooru/http/redirector.rb
+++ b/app/logical/danbooru/http/redirector.rb
@@ -1,6 +1,6 @@
 # A HTTP::Feature that automatically follows HTTP redirects.
-# https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections
-
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections
 module Danbooru
   class Http
     class Redirector < HTTP::Feature
diff --git a/app/logical/storage_manager/local.rb b/app/logical/storage_manager/local.rb
index b0bfcf402..f6c404819 100644
--- a/app/logical/storage_manager/local.rb
+++ b/app/logical/storage_manager/local.rb
@@ -1,3 +1,4 @@
+# A StorageManager that stores files on the local filesystem.
 class StorageManager::Local < StorageManager
   DEFAULT_PERMISSIONS = 0o644
 
diff --git a/app/logical/storage_manager/null.rb b/app/logical/storage_manager/null.rb
index 7164ef2ff..98cf9d8ef 100644
--- a/app/logical/storage_manager/null.rb
+++ b/app/logical/storage_manager/null.rb
@@ -1,3 +1,5 @@
+# A null StorageManager that doesn't store files at all. Used for testing or
+# disabling backups.
 class StorageManager::Null < StorageManager
   def initialize(base_url: "/", base_dir: "/")
     super
diff --git a/app/mailers/application_mailer.rb b/app/mailers/application_mailer.rb
index 965194ecd..c5ac3f494 100644
--- a/app/mailers/application_mailer.rb
+++ b/app/mailers/application_mailer.rb
@@ -1,3 +1,6 @@
+# The base class for emails sent by Danbooru.
+#
+# @see https://guides.rubyonrails.org/action_mailer_basics.html
 class ApplicationMailer < ActionMailer::Base
   default from: "#{Danbooru.config.canonical_app_name} <#{Danbooru.config.contact_email}>", content_type: "text/html"
 end
diff --git a/config/application.rb b/config/application.rb
index c39d2b697..39d354b38 100644
--- a/config/application.rb
+++ b/config/application.rb
@@ -1,5 +1,6 @@
-# This file runs after config/boot.rb and before config/environment.rb. It loads Rails, loads the gems, loads the
-# Danbooru configuration, and does some basic Rails configuration.
+# This file runs after config/boot.rb and before config/environment.rb. It loads
+# Rails, loads the gems, loads the Danbooru configuration, and does some basic
+# Rails configuration.
 #
 # @see https://guides.rubyonrails.org/initialization.html
 
@@ -21,8 +22,8 @@ require "rails/test_unit/railtie"
 # Load the gems for the current Rails environment from the Gemfile.
 Bundler.require(*Rails.groups)
 
-# Load the default Danbooru configuration from config/danbooru_default_config.rb and the custom config from
-# config/danbooru_local_config.rb.
+# Load the default Danbooru configuration from config/danbooru_default_config.rb
+# and the custom config from config/danbooru_local_config.rb.
 begin
   require_relative "danbooru_default_config"
   require_relative ENV.fetch("DANBOORU_CONFIG_FILE", "danbooru_local_config")
diff --git a/script/fixes/README.md b/script/fixes/README.md
index 7c17d4b50..e14fffca3 100644
--- a/script/fixes/README.md
+++ b/script/fixes/README.md
@@ -1,6 +1,6 @@
 # Fixes
 
-This directory contains fix scripts designed to fix various problems with the production database. Most of these scripts
-are for the production database and aren't meant to be run by downstream users.
+This directory contains one-off scripts designed to fix various problems with the production database. Most of these
+scripts are for the production database and aren't meant to be run by downstream users.
 
 Most of the older scripts here no longer work because of changes to the code over the years.
\ No newline at end of file