Merge pull request #17068 from mokhan/update-active-job-documentation

[ci-skip] Update Active Job API documentation

activejob/lib/active_job/arguments.rb

@@ -24,10 +24,16 @@ module ActiveJob
     extend self
     TYPE_WHITELIST = [ NilClass, Fixnum, Float, String, TrueClass, FalseClass, Bignum ]
 
+    # Serializes a set of arguments. Whitelisted types are returned
+    # as-is. Arrays/Hashes are serialized element by element.
+    # All other types are serialized using GlobalID.
     def serialize(arguments)
       arguments.map { |argument| serialize_argument(argument) }
     end
 
+    # Deserializes a set of arguments. Whitelisted types are returned
+    # as-is. Arrays/Hashes are deserialized element by element.
+    # All other types are deserialized using GlobalID.
     def deserialize(arguments)
       arguments.map { |argument| deserialize_argument(argument) }
     rescue => e

activejob/lib/active_job/base.rb

@@ -6,7 +6,48 @@ require 'active_job/execution'
 require 'active_job/callbacks'
 require 'active_job/logging'
 
-module ActiveJob
+module ActiveJob #:nodoc:
+  # = Active Job
+  #
+  # Active job objects can be configured to work with different backend
+  # queuing frameworks. To specify a queue adapter to use:
+  #
+  #   ActiveJob::Base.queue_adapter = :inline
+  #
+  # A list of supported adapters can be found in QueueAdapters.
+  #
+  # Active job objects can be defined by creating a class that inherits
+  # from the ActiveJob::Base class. The only necessary method to
+  # implement is the "perform" method.
+  #
+  # To define an Active Job object:
+  #
+  #   class ProcessPhotoJob < ActiveJob::Base
+  #     def perform(photo)
+  #       photo.watermark!('Rails')
+  #       photo.rotate!(90.degrees)
+  #       photo.resize_to_fit!(300, 300)
+  #       photo.upload!
+  #     end
+  #   end
+  #
+  # Records that are passed in are serialized/deserialized using Global
+  # Id. More information can be found in Arguments.
+  #
+  # To queue a job to be processed asynchronously immediately:
+  #
+  #   ProcessPhotoJob.perform_later(photo)
+  #
+  # To queue a job to be processed at some point in the future:
+  #
+  #   ProcessPhotoJob.set(wait_until: Date.tomorrow.noon).perform_later(photo)
+  #
+  # More information can be found in ActiveJob::Core::ClassMethods#set
+  #
+  # == Exceptions
+  #
+  # * DeserializationError - Error class for deserialization errors.
+  # * SerializationError - Error class for serialization errors.
   class Base
     include Core
     include QueueAdapter

activejob/lib/active_job/logging.rb

@@ -3,7 +3,7 @@ require 'active_support/tagged_logging'
 require 'active_support/logger'
 
 module ActiveJob
-  module Logging
+  module Logging #:nodoc:
     extend ActiveSupport::Concern
 
     included do

activejob/lib/active_job/queue_adapter.rb

@@ -2,12 +2,15 @@ require 'active_job/queue_adapters/inline_adapter'
 require 'active_support/core_ext/string/inflections'
 
 module ActiveJob
-  module QueueAdapter
+  module QueueAdapter #:nodoc:
     extend ActiveSupport::Concern
 
     module ClassMethods
       mattr_reader(:queue_adapter) { ActiveJob::QueueAdapters::InlineAdapter }
 
+      # Specify the backend queue provider. The default queue adapter
+      # is the :inline queue. See QueueAdapters for more
+      # information.
       def queue_adapter=(name_or_adapter)
         @@queue_adapter = \
           case name_or_adapter

activejob/lib/active_job/queue_name.rb

@@ -6,6 +6,15 @@ module ActiveJob
       mattr_accessor(:queue_name_prefix)
       mattr_accessor(:default_queue_name) { "default" }
 
+      # Specifies the name of the queue to process the job on.
+      #
+      #   class PublishToFeedJob < ActiveJob::Base
+      #     queue_as :feeds
+      #
+      #     def perform(post)
+      #       post.to_feed!
+      #     end
+      #   end
       def queue_as(part_name=nil, &block)
         if block_given?
           self.queue_name = block

guides/source/4_2_release_notes.md

@@ -753,7 +753,7 @@ Please refer to the [Changelog][active-support] for detailed changes.
 *   Introduced new configuration option `active_support.test_order` for
     specifying the order test cases are executed. This option currently defaults
     to `:sorted` but will be changed to `:random` in Rails 5.0.
-    ([Commit](TODO: fill me in))
+    ([Commit](https://github.com/rails/rails/commit/53e877f7d9291b2bf0b8c425f9e32ef35829f35b))
 
 *   The `travel_to` test helper now truncates the `usec` component to 0.
     ([Commit](https://github.com/rails/rails/commit/9f6e82ee4783e491c20f5244a613fdeb4024beb5))