Added docs for AJ::Callbacks; Added AJ to docs build map

1 files changed, 108 insertions, 4 deletions

diff --git a/activejob/lib/active_job/callbacks.rb b/activejob/lib/active_job/callbacks.rb
index c69e4a3b55..af92031bc9 100644
--- a/activejob/lib/active_job/callbacks.rb
+++ b/activejob/lib/active_job/callbacks.rb
@@ -1,40 +1,144 @@
 require 'active_support/callbacks'
 
 module ActiveJob
+  # = Active Job Callbacks
+  #
+  # Active Job provides hooks during the lifecycle of a job. Callbacks allows you to trigger
+  # logic during the lifecycle of a job. Available callbacks:
+  #
+  # * <tt>before_enqueue</tt>
+  # * <tt>around_enqueue</tt>
+  # * <tt>after_enqueue</tt>
+  # * <tt>before_perform</tt>
+  # * <tt>around_perform</tt>
+  # * <tt>after_perform</tt>
+  #
   module Callbacks
     extend  ActiveSupport::Concern
     include ActiveSupport::Callbacks
-    
+
     included do
       define_callbacks :perform
       define_callbacks :enqueue
     end
-    
+
     module ClassMethods
+      # Defines a callback that will get called right before the
+      # job's perform method is executed.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_perform do |job|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def before_perform(*filters, &blk)
         set_callback(:perform, :before, *filters, &blk)
       end
 
+      # Defines a callback that will get called right after the
+      # job's perform method has finished.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_perform do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def after_perform(*filters, &blk)
         set_callback(:perform, :after, *filters, &blk)
       end
 
+      # Defines a callback that will get called around the job's perform method.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_perform do |job, block|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #       block.call
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def around_perform(*filters, &blk)
         set_callback(:perform, :around, *filters, &blk)
       end
 
-
+      # Defines a callback that will get called right before the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def before_enqueue(*filters, &blk)
         set_callback(:enqueue, :before, *filters, &blk)
       end
 
+      # Defines a callback that will get called right after the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.success"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def after_enqueue(*filters, &blk)
         set_callback(:enqueue, :after, *filters, &blk)
       end
 
+      # Defines a callback that will get called before and after the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_enqueue do |job, block|
+      #       $statsd.time "video-job.process" do
+      #         block.call
+      #       end
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      # end
+      #
       def around_enqueue(*filters, &blk)
         set_callback(:enqueue, :around, *filters, &blk)
       end
     end
   end
-end
\ No newline at end of file
+end