minor tweaks in Active Storage after a walkthrough

1 files changed, 16 insertions, 17 deletions

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)