Merge pull request #30060 from bdewater/aj-callback-docs

Improve callback examples in Active Job guide

1 files changed, 30 insertions, 22 deletions

diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index 443be77934..2606bfe280 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -260,40 +260,48 @@ backends you need to specify the queues to listen to.
 Callbacks
 ---------
 
-Active Job provides hooks during the life cycle of a job. Callbacks allow you to
-trigger logic during the life cycle of a job.
-
-### Available callbacks
-
-* `before_enqueue`
-* `around_enqueue`
-* `after_enqueue`
-* `before_perform`
-* `around_perform`
-* `after_perform`
-
-### Usage
+Active Job provides hooks to trigger logic during the life cycle of a job. Like
+other callbacks in Rails, you can implement the callbacks as ordinary methods
+and use a macro-style class method to register them as callbacks:
 
 ```ruby
 class GuestsCleanupJob < ApplicationJob
   queue_as :default
 
-  before_enqueue do |job|
-    # Do something with the job instance
-  end
-
-  around_perform do |job, block|
-    # Do something before perform
-    block.call
-    # Do something after perform
-  end
+  around_perform :around_cleanup
 
   def perform
     # Do something later
   end
+
+  private
+    def around_cleanup(job)
+      # Do something before perform
+      yield
+      # Do something after perform
+    end
 end
 ```
 
+The macro-style class methods can also receive a block. Consider using this
+style if the code inside your block is so short that it fits in a single line.
+For example, you could send metrics for every job enqueued:
+
+```ruby
+class ApplicationJob
+  before_enqueue { |job| $statsd.increment "#{job.name.underscore}.enqueue" }
+end
+```
+
+### Available callbacks
+
+* `before_enqueue`
+* `around_enqueue`
+* `after_enqueue`
+* `before_perform`
+* `around_perform`
+* `after_perform`
+
 
 Action Mailer
 ------------