diff --git a/activestorage/app/controllers/concerns/active_storage/set_current.rb b/activestorage/app/controllers/concerns/active_storage/set_current.rb
index c00bf09330ffc..5afe4492b5144 100644
--- a/activestorage/app/controllers/concerns/active_storage/set_current.rb
+++ b/activestorage/app/controllers/concerns/active_storage/set_current.rb
@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Sets the <tt>ActiveStorage::Current.url_options</tt> attribute, which the disk service uses to generate URLs.
+# Sets the ActiveStorage::Current.url_options attribute, which the disk service uses to generate URLs.
 # Include this concern in custom controllers that call ActiveStorage::Blob#url,
 # ActiveStorage::Variant#url, or ActiveStorage::Preview#url so the disk service can
 # generate URLs using the same host, protocol, and port as the current request.
+#
+# See also ActiveStorage::Current for details.
 module ActiveStorage::SetCurrent
   extend ActiveSupport::Concern
 
diff --git a/activestorage/app/models/active_storage/current.rb b/activestorage/app/models/active_storage/current.rb
index b282707ddacec..82acb52c8e539 100644
--- a/activestorage/app/models/active_storage/current.rb
+++ b/activestorage/app/models/active_storage/current.rb
@@ -1,5 +1,38 @@
 # frozen_string_literal: true
 
-class ActiveStorage::Current < ActiveSupport::CurrentAttributes # :nodoc:
+# = Active Storage \Current
+#
+# Disk service for development and testing is a special case
+# as it requires protocol, host and port specified additionally
+# in order to generate url, which non-disk services can usually dispense with.
+# 
+# Use ActiveStorage::SetCurrent to effectively test the custom controllers' behavior
+# to generate url no matter what type of service underlies the storage.
+#
+#   class UsersController < ApplicationController
+#     include ActiveStorage::SetCurrent
+#
+#     def show
+#       @user = User.find(params[:id])
+#       @url = @user.profile.url
+#     end
+#   end
+#
+# If including the module like above does not help because, for example,
+# controllers do not participate in generating url, use Current.url_options= but with caution.
+# Knowing the nature of ActiveSupport::CurrentAttributes would be of help.
+class ActiveStorage::Current < ActiveSupport::CurrentAttributes
+  ##
+  # :singleton-method: url_options
+  #
+  # Returns the options for the current request.
+
+  ##
+  # :singleton-method: url_options=
+  # :call-seq: url_options=(options)
+  #
+  # Sets the options for the current request.
+  # For the supported options, see ActionDispatch::Routing::UrlFor#url_for.
+
   attribute :url_options
 end
diff --git a/activestorage/lib/active_storage/service/disk_service.rb b/activestorage/lib/active_storage/service/disk_service.rb
index ee49bf6b6c59f..5aa290d652e06 100644
--- a/activestorage/lib/active_storage/service/disk_service.rb
+++ b/activestorage/lib/active_storage/service/disk_service.rb
@@ -135,7 +135,7 @@ def generate_url(key, expires_in:, filename:, content_type:, disposition:)
         )
 
         if url_options.blank?
-          raise ArgumentError, "Cannot generate URL for #{filename} using Disk service, please set ActiveStorage::Current.url_options."
+          raise ArgumentError, "Cannot generate URL for #{filename} using Disk service. Consider using ActiveStorage::SetCurrent."
         end
 
         url_helpers.rails_disk_service_url(verified_key_with_expiration, filename: filename, **url_options)
diff --git a/activestorage/test/service/disk_service_test.rb b/activestorage/test/service/disk_service_test.rb
index 4a3413323029c..35f2b2246d7a8 100644
--- a/activestorage/test/service/disk_service_test.rb
+++ b/activestorage/test/service/disk_service_test.rb
@@ -46,7 +46,7 @@ class ActiveStorage::Service::DiskServiceTest < ActiveSupport::TestCase
       @service.url(@key, expires_in: 5.minutes, disposition: :inline, filename: ActiveStorage::Filename.new("avatar.png"), content_type: "image/png")
     end
 
-    assert_equal("Cannot generate URL for avatar.png using Disk service, please set ActiveStorage::Current.url_options.", error.message)
+    assert_equal("Cannot generate URL for avatar.png using Disk service. Consider using ActiveStorage::SetCurrent.", error.message)
   end
 
   test "URL generation keeps working with ActiveStorage::Current.host set" do