minor tweaks in Active Storage after a walkthrough

6 files changed, 28 insertions, 32 deletions

diff --git a/activestorage/app/controllers/active_storage/disk_controller.rb b/activestorage/app/controllers/active_storage/disk_controller.rb
index b10d4e2cac..dee88054da 100644
--- a/activestorage/app/controllers/active_storage/disk_controller.rb
+++ b/activestorage/app/controllers/active_storage/disk_controller.rb
@@ -33,7 +33,6 @@ class ActiveStorage::DiskController < ActionController::Base
       ActiveStorage::Blob.service
     end
 
-
     def decode_verified_key
       ActiveStorage.verifier.verified(params[:encoded_key], purpose: :blob_key)
     end
@@ -42,7 +41,6 @@ class ActiveStorage::DiskController < ActionController::Base
       params[:disposition].presence_in(%w( inline attachment )) || "inline"
     end
 
-
     def decode_verified_token
       ActiveStorage.verifier.verified(params[:encoded_token], purpose: :blob_token)
     end
diff --git a/activestorage/app/jobs/active_storage/purge_job.rb b/activestorage/app/jobs/active_storage/purge_job.rb
index 404ccefd05..369c07929d 100644
--- a/activestorage/app/jobs/active_storage/purge_job.rb
+++ b/activestorage/app/jobs/active_storage/purge_job.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Provides delayed purging of attachments or blobs using their +#purge_later+ method.
+# Provides delayed purging of attachments or blobs using their +purge_later+ method.
 class ActiveStorage::PurgeJob < ActiveJob::Base
   # FIXME: Limit this to a custom ActiveStorage error
   retry_on StandardError
diff --git a/activestorage/app/models/active_storage/attachment.rb b/activestorage/app/models/active_storage/attachment.rb
index adfa6d4aa5..ad43845e4e 100644
--- a/activestorage/app/models/active_storage/attachment.rb
+++ b/activestorage/app/models/active_storage/attachment.rb
@@ -4,7 +4,7 @@ require "active_support/core_ext/module/delegation"
 
 # Attachments associate records with blobs. Usually that's a one record-many blobs relationship,
 # but it is possible to associate many different records with the same blob. If you're doing that,
-# you'll want to declare with `has_one/many_attached :thingy, dependent: false`, so that destroying
+# you'll want to declare with <tt>has_one/many_attached :thingy, dependent: false</tt>, so that destroying
 # any one record won't destroy the blob as well. (Then you'll need to do your own garbage collecting, though).
 class ActiveStorage::Attachment < ActiveRecord::Base
   self.table_name = "active_storage_attachments"
@@ -22,8 +22,8 @@ class ActiveStorage::Attachment < ActiveRecord::Base
   end
 
   # Purging an attachment means purging the blob, which means talking to the service, which means
-  # talking over the internet. Whenever you're doing that, it's a good idea to put that work in a job,
-  # so it doesn't hold up other operations. That's what +#purge_later+ provides.
+  # talking over the Internet. Whenever you're doing that, it's a good idea to put that work in a job,
+  # so it doesn't hold up other operations. That's what +purge_later+ provides.
   def purge_later
     ActiveStorage::PurgeJob.perform_later(self)
   end
diff --git a/activestorage/app/models/active_storage/blob.rb b/activestorage/app/models/active_storage/blob.rb
index dc91a9265f..36b8a35778 100644
--- a/activestorage/app/models/active_storage/blob.rb
+++ b/activestorage/app/models/active_storage/blob.rb
@@ -3,8 +3,8 @@
 # A blob is a record that contains the metadata about a file and a key for where that file resides on the service.
 # Blobs can be created in two ways:
 #
-# 1) Subsequent to the file being uploaded server-side to the service via #create_after_upload!
-# 2) Ahead of the file being directly uploaded client-side to the service via #create_before_direct_upload!
+# 1) Subsequent to the file being uploaded server-side to the service via <tt>create_after_upload!</tt>.
+# 2) Ahead of the file being directly uploaded client-side to the service via <tt>create_before_direct_upload!</tt>.
 #
 # The first option doesn't require any client-side JavaScript integration, and can be used by any other back-end
 # service that deals with files. The second option is faster, since you're not using your own server as a staging
@@ -12,7 +12,7 @@
 #
 # Blobs are intended to be immutable in as-so-far as their reference to a specific file goes. You're allowed to
 # update a blob's metadata on a subsequent pass, but you should not update the key or change the uploaded file.
-# If you need to create a derivative or otherwise change the blob, simply create a new blob and purge the old.
+# If you need to create a derivative or otherwise change the blob, simply create a new blob and purge the old one.
 class ActiveStorage::Blob < ActiveRecord::Base
   self.table_name = "active_storage_blobs"
 
@@ -22,11 +22,11 @@ class ActiveStorage::Blob < ActiveRecord::Base
   class_attribute :service
 
   class << self
-    # You can used the signed id of a blob to refer to it on the client side without fear of tampering.
-    # This is particularly helpful for direct uploads where the client side needs to refer to the blob
+    # You can used the signed ID of a blob to refer to it on the client side without fear of tampering.
+    # This is particularly helpful for direct uploads where the client-side needs to refer to the blob
     # that was created ahead of the upload itself on form submission.
     #
-    # The signed id is also used to create stable URLs for the blob through the BlobsController.
+    # The signed ID is also used to create stable URLs for the blob through the BlobsController.
     def find_signed(id)
       find ActiveStorage.verifier.verify(id, purpose: :blob_id)
     end
@@ -43,8 +43,8 @@ class ActiveStorage::Blob < ActiveRecord::Base
     end
 
     # Returns a saved blob instance after the +io+ has been uploaded to the service. Note, the blob is first built,
-    # then the +io+ is uploaded, then the blob is saved. This is doing to avoid opening a transaction and talking to
-    # the service during that (which is a bad idea and leads to deadlocks).
+    # then the +io+ is uploaded, then the blob is saved. This is done this way to avoid uploading (which may take
+    # time), while having an open database transaction.
     def create_after_upload!(io:, filename:, content_type: nil, metadata: nil)
       build_after_upload(io: io, filename: filename, content_type: content_type, metadata: metadata).tap(&:save!)
     end
@@ -59,9 +59,8 @@ class ActiveStorage::Blob < ActiveRecord::Base
     end
   end
 
-
   # Returns a signed ID for this blob that's suitable for reference on the client-side without fear of tampering.
-  # It uses the framework-wide verifier on `ActiveStorage.verifier`, but with a dedicated purpose.
+  # It uses the framework-wide verifier on <tt>ActiveStorage.verifier</tt>, but with a dedicated purpose.
   def signed_id
     ActiveStorage.verifier.generate(id, purpose: :blob_id)
   end
@@ -74,8 +73,9 @@ class ActiveStorage::Blob < ActiveRecord::Base
     self[:key] ||= self.class.generate_unique_secure_token
   end
 
-  # Returns a ActiveStorage::Filename instance of the filename that can be queried for basename, extension, and
-  # a sanitized version of the filename that's safe to use in URLs.
+  # Returns an ActiveStorage::Filename instance of the filename that can be
+  # queried for basename, extension, and a sanitized version of the filename
+  # that's safe to use in URLs.
   def filename
     ActiveStorage::Filename.new(self[:filename])
   end
@@ -100,8 +100,9 @@ class ActiveStorage::Blob < ActiveRecord::Base
     content_type.start_with?("text")
   end
 
-  # Returns a ActiveStorage::Variant instance with the set of +transformations+ passed in. This is only relevant
-  # for image files, and it allows any image to be transformed for size, colors, and the like. Example:
+  # Returns an ActiveStorage::Variant instance with the set of +transformations+
+  # passed in. This is only relevant for image files, and it allows any image to
+  # be transformed for size, colors, and the like. Example:
   #
   #   avatar.variant(resize: "100x100").processed.service_url
   #
@@ -119,7 +120,6 @@ class ActiveStorage::Blob < ActiveRecord::Base
     ActiveStorage::Variant.new(self, ActiveStorage::Variation.new(transformations))
   end
 
-
   # Returns the URL of the blob on the service. This URL is intended to be short-lived for security and not used directly
   # with users. Instead, the +service_url+ should only be exposed as a redirect from a stable, possibly authenticated URL.
   # Hiding the +service_url+ behind a redirect also gives you the power to change services without updating all URLs. And
@@ -162,7 +162,6 @@ class ActiveStorage::Blob < ActiveRecord::Base
     service.download key, &block
   end
 
-
   # Deletes the file on the service that's associated with this blob. This should only be done if the blob is going to be
   # deleted as well or you will essentially have a dead reference. It's recommended to use the +#purge+ and +#purge_later+
   # methods in most circumstances.
@@ -178,7 +177,7 @@ class ActiveStorage::Blob < ActiveRecord::Base
     destroy
   end
 
-  # Enqueues a ActiveStorage::PurgeJob job that'll call +#purge+. This is the recommended way to purge blobs when the call
+  # Enqueues an ActiveStorage::PurgeJob job that'll call +purge+. This is the recommended way to purge blobs when the call
   # needs to be made from a transaction, a callback, or any other real-time scenario.
   def purge_later
     ActiveStorage::PurgeJob.perform_later(self)
diff --git a/activestorage/app/models/active_storage/variant.rb b/activestorage/app/models/active_storage/variant.rb
index 7b4ca18c8c..92fa445095 100644
--- a/activestorage/app/models/active_storage/variant.rb
+++ b/activestorage/app/models/active_storage/variant.rb
@@ -4,8 +4,8 @@
 # These variants are used to create thumbnails, fixed-size avatars, or any other derivative image from the
 # original.
 #
-# Variants rely on `MiniMagick` for the actual transformations of the file, so you must add `gem "mini_magick"`
-# to your Gemfile if you wish to use variants.
+# Variants rely on {MiniMagick}(https://github.com/minimagick/minimagick) for the actual transformations
+# of the file, so you must add <tt>gem "mini_magick"</tt> to your Gemfile if you wish to use variants.
 #
 # Note that to create a variant it's necessary to download the entire blob file from the service and load it
 # into memory. The larger the image, the more memory is used. Because of this process, you also want to be
@@ -21,7 +21,7 @@
 # This will create a URL for that specific blob with that specific variant, which the ActiveStorage::VariantsController
 # can then produce on-demand.
 #
-# When you do want to actually produce the variant needed, call +#processed+. This will check that the variant
+# When you do want to actually produce the variant needed, call +processed+. This will check that the variant
 # has already been processed and uploaded to the service, and, if so, just return that. Otherwise it will perform
 # the transformations, upload the variant to the service, and return itself again. Example:
 #
@@ -58,14 +58,13 @@ class ActiveStorage::Variant
   # Hiding the +service_url+ behind a redirect also gives you the power to change services without updating all URLs. And
   # it allows permanent URLs that redirect to the +service_url+ to be cached in the view.
   #
-  # Use `url_for(variant)` (or the implied form, like `link_to variant` or `redirect_to variant`) to get the stable URL
-  # for a variant that points to the ActiveStorage::VariantsController, which in turn will use this +#service_call+ method
+  # Use <tt>url_for(variant)</tt> (or the implied form, like +link_to variant+ or +redirect_to variant+) to get the stable URL
+  # for a variant that points to the ActiveStorage::VariantsController, which in turn will use this +service_call+ method
   # for its redirection.
   def service_url(expires_in: 5.minutes, disposition: :inline)
     service.url key, expires_in: expires_in, disposition: disposition, filename: blob.filename, content_type: blob.content_type
   end
 
-
   private
     def processed?
       service.exist?(key)
diff --git a/activestorage/app/models/active_storage/variation.rb b/activestorage/app/models/active_storage/variation.rb
index 396ce85ef1..f657d90db4 100644
--- a/activestorage/app/models/active_storage/variation.rb
+++ b/activestorage/app/models/active_storage/variation.rb
@@ -15,13 +15,13 @@ class ActiveStorage::Variation
   attr_reader :transformations
 
   class << self
-    # Returns a variation instance with the transformations that were encoded by +#encode+.
+    # Returns a variation instance with the transformations that were encoded by +encode+.
     def decode(key)
       new ActiveStorage.verifier.verify(key, purpose: :variation)
     end
 
     # Returns a signed key for the +transformations+, which can be used to refer to a specific
-    # variation in a URL or combined key (like `ActiveStorage::Variant#key`).
+    # variation in a URL or combined key (like <tt>ActiveStorage::Variant#key</tt>).
     def encode(transformations)
       ActiveStorage.verifier.generate(transformations, purpose: :variation)
     end
@@ -31,7 +31,7 @@ class ActiveStorage::Variation
     @transformations = transformations
   end
 
-  # Accepts an open MiniMagick image instance, like what's return by `MiniMagick::Image.read(io)`,
+  # Accepts an open MiniMagick image instance, like what's returned by <tt>MiniMagick::Image.read(io)</tt>,
   # and performs the +transformations+ against it. The transformed image instance is then returned.
   def transform(image)
     transformations.each do |(method, argument)|