4 files changed, 17 insertions, 9 deletions
diff --git a/activestorage/app/models/active_storage/blob.rb b/activestorage/app/models/active_storage/blob.rb
index 664a53a778..e6cf08ce83 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 <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>.
+# 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
diff --git a/activestorage/app/models/active_storage/filename.rb b/activestorage/app/models/active_storage/filename.rb
index 10b1116d52..dead6b6d33 100644
--- a/activestorage/app/models/active_storage/filename.rb
+++ b/activestorage/app/models/active_storage/filename.rb
@@ -9,25 +9,33 @@ class ActiveStorage::Filename
     @filename = filename
   end
 
-  # Filename.new("racecar.jpg").base # => "racecar"
+  # Returns the basename of the filename.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").base # => "racecar"
   def base
     File.basename @filename, extension_with_delimiter
   end
 
-  # Filename.new("racecar.jpg").extension_with_delimiter # => ".jpg"
+  # Returns the extension with delimiter of the filename.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").extension_with_delimiter # => ".jpg"
   def extension_with_delimiter
     File.extname @filename
   end
 
-  # Filename.new("racecar.jpg").extension_without_delimiter # => "jpg"
+  # Returns the extension without delimiter of the filename.
+  #
+  #   ActiveStorage::Filename.new("racecar.jpg").extension_without_delimiter # => "jpg"
   def extension_without_delimiter
     extension_with_delimiter.from(1).to_s
   end
 
   alias_method :extension, :extension_without_delimiter
 
-  # Filename.new("foo:bar.jpg").sanitized # => "foo-bar.jpg"
-  # Filename.new("foo/bar.jpg").sanitized # => "foo-bar.jpg"
+  # Returns the sanitized filename.
+  #
+  #   ActiveStorage::Filename.new("foo:bar.jpg").sanitized # => "foo-bar.jpg"
+  #   ActiveStorage::Filename.new("foo/bar.jpg").sanitized # => "foo-bar.jpg"
   #
   # ...and any other character unsafe for URLs or storage is converted or stripped.
   def sanitized
diff --git a/activestorage/lib/active_storage/attached/one.rb b/activestorage/lib/active_storage/attached/one.rb
index 2e5831348e..92a00c20a7 100644
--- a/activestorage/lib/active_storage/attached/one.rb
+++ b/activestorage/lib/active_storage/attached/one.rb
@@ -25,7 +25,7 @@ module ActiveStorage
         ActiveStorage::Attachment.create!(record: record, name: name, blob: create_blob_from(attachable))
     end
 
-    # Returns true if an attachment has been made.
+    # Returns +true+ if an attachment has been made.
     #
     #   class User < ActiveRecord::Base
     #     has_one_attached :avatar
diff --git a/activestorage/lib/active_storage/service.rb b/activestorage/lib/active_storage/service.rb
index ce736b8728..b80fdea1ab 100644
--- a/activestorage/lib/active_storage/service.rb
+++ b/activestorage/lib/active_storage/service.rb
@@ -77,7 +77,7 @@ module ActiveStorage
       raise NotImplementedError
     end
 
-    # Return true if a file exists at the +key+.
+    # Return +true+ if a file exists at the +key+.
     def exist?(key)
       raise NotImplementedError
     end