Document queue_as block arguments and their use

Currently, we only document the use case for ActiveJob's `queue_as` block
arguments in [Rails Guides][1]. It seems necessary to document them in the API
docs as well considering how useful and powerful this option is.

[1]: https://edgeguides.rubyonrails.org/active_job_basics.html#queues

[ci skip]

1 files changed, 20 insertions, 0 deletions

diff --git a/activejob/lib/active_job/queue_name.rb b/activejob/lib/active_job/queue_name.rb
index 7bb1e35181..de259261de 100644
--- a/activejob/lib/active_job/queue_name.rb
+++ b/activejob/lib/active_job/queue_name.rb
@@ -18,6 +18,26 @@ module ActiveJob
       #       post.to_feed!
       #     end
       #   end
+      #
+      # Can be given a block that will evaluate in the context of the job
+      # allowing +self.arguments+ to be accessed so that a dynamic queue name
+      # can be applied:
+      #
+      #   class PublishToFeedJob < ApplicationJob
+      #     queue_as do
+      #       post = self.arguments.first
+      #
+      #       if post.paid?
+      #         :paid_feeds
+      #       else
+      #         :feeds
+      #       end
+      #     end
+      #
+      #     def perform(post)
+      #       post.to_feed!
+      #     end
+      #   end
       def queue_as(part_name = nil, &block)
         if block_given?
           self.queue_name = block