Merge branch 'master' of github.com:rails/rails

5 files changed, 109 insertions, 30 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 9aae14ec8c..f539fc53c6 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -138,9 +138,20 @@ module ActionMailer
   # Once a mailer action and template are defined, you can deliver your message or create it and save it
   # for delivery later:
   #
-  #   Notifier.welcome(david).deliver # sends the email
-  #   mail = Notifier.welcome(david)  # => a Mail::Message object
-  #   mail.deliver                    # sends the email
+  #   Notifier.welcome(User.first).deliver_now # sends the email
+  #   mail = Notifier.welcome(User.first)      # => an ActionMailer::MessageDelivery object
+  #   mail.deliver_now                    # sends the email
+  #
+  # The <tt>ActionMailer::MessageDelivery</tt> class is a wrapper around a <tt>Mail::Message</tt> object. If
+  # you want direct access to the <tt>Mail::Message</tt> object you can call the <tt>message</tt> method on
+  # the <tt>ActionMailer::MessageDelivery</tt> object.
+  #
+  #   Notifier.welcome(User.first).message     # => a Mail::Message object
+  #
+  # Action Mailer is nicely integrated with Active Job so you can send emails in the background (example: outside
+  # of the request-response cycle, so the user doesn't have to wait on it):
+  #
+  #   Notifier.welcome(User.first).deliver_later # enqueue the email sending to Active Job
   #
   # You never instantiate your mailer class. Rather, you just call the method you defined on the class itself.
   #
@@ -322,8 +333,8 @@ module ActionMailer
   #   end
   #
   # Methods must return a <tt>Mail::Message</tt> object which can be generated by calling the mailer
-  # method without the additional <tt>deliver</tt>. The location of the mailer previews
-  # directory can be configured using the <tt>preview_path</tt> option which has a default
+  # method without the additional <tt>deliver_now</tt> / <tt>deliver_later</tt>. The location of the
+  # mailer previews directory can be configured using the <tt>preview_path</tt> option which has a default
   # of <tt>test/mailers/previews</tt>:
   #
   #   config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"
diff --git a/actionmailer/lib/action_mailer/delivery_job.rb b/actionmailer/lib/action_mailer/delivery_job.rb
index b2cfa245fd..622f202695 100644
--- a/actionmailer/lib/action_mailer/delivery_job.rb
+++ b/actionmailer/lib/action_mailer/delivery_job.rb
@@ -1,10 +1,10 @@
 require 'active_job'
 
 module ActionMailer
-  class DeliveryJob < ActiveJob::Base
+  class DeliveryJob < ActiveJob::Base #:nodoc:
     queue_as :mailers
 
-    def perform(mailer, mail_method, delivery_method, *args)
+    def perform(mailer, mail_method, delivery_method, *args) #:nodoc#
       mailer.constantize.public_send(mail_method, *args).send(delivery_method)
     end
   end
diff --git a/actionmailer/lib/action_mailer/message_delivery.rb b/actionmailer/lib/action_mailer/message_delivery.rb
index 80a0517bff..30425d38f9 100644
--- a/actionmailer/lib/action_mailer/message_delivery.rb
+++ b/actionmailer/lib/action_mailer/message_delivery.rb
@@ -1,45 +1,112 @@
 require 'delegate'
 
 module ActionMailer
+
+  # The <tt>ActionMailer::MessageDelivery</tt> class is used by
+  # <tt>ActionMailer::Base</tt> when creating a new mailer.
+  # <tt>MessageDelivery</tt> is a wrapper (+Delegator+ subclass) around a lazy
+  # created <tt>Mail::Message</tt>. You can get direct access to the
+  # <tt>Mail::Message</tt>, deliver the email or schedule the email to be sent
+  # through Active Job.
+  #
+  #   Notifier.welcome(User.first)               # an ActionMailer::MessageDelivery object
+  #   Notifier.welcome(User.first).deliver_now   # sends the email
+  #   Notifier.welcome(User.first).deliver_later # enqueue email delivery as a job through Active Job
+  #   Notifier.welcome(User.first).message       # a Mail::Message object
   class MessageDelivery < Delegator
-    def initialize(mailer, mail_method, *args)
+    def initialize(mailer, mail_method, *args) #:nodoc:
       @mailer = mailer
       @mail_method = mail_method
       @args = args
     end
 
-    def __getobj__
+    def __getobj__ #:nodoc:
       @obj ||= @mailer.send(:new, @mail_method, *@args).message
     end
 
-    def __setobj__(obj)
+    def __setobj__(obj) #:nodoc:
       @obj = obj
     end
 
-    def message #:nodoc:
+    # Returns the Mail::Message object
+    def message
       __getobj__
     end
 
+    # Enqueues the email to be delivered through Active Job. When the
+    # job runs it will send the email using +deliver_now!+. That means
+    # that the message will be sent bypassing checking +perform_deliveries+
+    # and +raise_delivery_errors+, so use with caution.
+    #
+    #   Notifier.welcome(User.first).deliver_later
+    #   Notifier.welcome(User.first).deliver_later(in: 1.hour)
+    #   Notifier.welcome(User.first).deliver_later(at: 10.hours.from_now)
+    #
+    # Options:
+    #
+    # * <tt>:in</tt> - Enqueue the email to be delivered with a delay
+    # * <tt>:at</tt> - Enqueue the email to be delivered at (after) a specific date / time
     def deliver_later!(options={})
-      enqueue_delivery :deliver!, options
+      enqueue_delivery :deliver_now!, options
     end
 
+    # Enqueues the email to be delivered through Active Job. When the
+    # job runs it will send the email using +deliver_now+.
+    #
+    #   Notifier.welcome(User.first).deliver_later
+    #   Notifier.welcome(User.first).deliver_later(in: 1.hour)
+    #   Notifier.welcome(User.first).deliver_later(at: 10.hours.from_now)
+    #
+    # Options:
+    #
+    # * <tt>:in</tt> - Enqueue the email to be delivered with a delay
+    # * <tt>:at</tt> - Enqueue the email to be delivered at (after) a specific date / time
     def deliver_later(options={})
-      enqueue_delivery :deliver, options
+      enqueue_delivery :deliver_now, options
+    end
+
+    # Delivers an email without checking +perform_deliveries+ and +raise_delivery_errors+,
+    # so use with caution.
+    #
+    #   Notifier.welcome(User.first).deliver_now!
+    #
+    def deliver_now!
+      message.deliver!
+    end
+
+    # Delivers an email:
+    #
+    #   Notifier.welcome(User.first).deliver_now
+    #
+    def deliver_now
+      message.deliver
+    end
+
+    def deliver! #:nodoc:
+      ActiveSupport::Deprecation.warn "#deliver! is deprecated and will be removed in Rails 5. " \
+        "Use #deliver_now! to deliver immediately or #deliver_later! to deliver through Active Job."
+      deliver_now!
+    end
+
+    def deliver #:nodoc:
+      ActiveSupport::Deprecation.warn "#deliver is deprecated and will be removed in Rails 5. " \
+        "Use #deliver_now to deliver immediately or #deliver_later to deliver through Active Job."
+      deliver_now
     end
 
     private
-    def enqueue_delivery(delivery_method, options={})
-      args = @mailer.name, @mail_method.to_s, delivery_method.to_s, *@args
-      enqueue_method = :enqueue
-      if options[:at]
-        enqueue_method = :enqueue_at
-        args.unshift options[:at]
-      elsif options[:in]
-        enqueue_method = :enqueue_in
-        args.unshift options[:in]
+
+      def enqueue_delivery(delivery_method, options={})
+        args = @mailer.name, @mail_method.to_s, delivery_method.to_s, *@args
+        enqueue_method = :enqueue
+        if options[:at]
+          enqueue_method = :enqueue_at
+          args.unshift options[:at]
+        elsif options[:in]
+          enqueue_method = :enqueue_in
+          args.unshift options[:in]
+        end
+        ActionMailer::DeliveryJob.send enqueue_method, *args
       end
-      ActionMailer::DeliveryJob.send enqueue_method, *args
-    end
   end
 end
diff --git a/actionmailer/lib/action_mailer/railtie.rb b/actionmailer/lib/action_mailer/railtie.rb
index c62d4b5082..05a3ac6a21 100644
--- a/actionmailer/lib/action_mailer/railtie.rb
+++ b/actionmailer/lib/action_mailer/railtie.rb
@@ -1,3 +1,4 @@
+require 'active_job/railtie'
 require "action_mailer"
 require "rails"
 require "abstract_controller/railties/routes_helpers"
diff --git a/actionmailer/lib/action_mailer/test_helper.rb b/actionmailer/lib/action_mailer/test_helper.rb
index 06da0dd27e..6ddacf7b79 100644
--- a/actionmailer/lib/action_mailer/test_helper.rb
+++ b/actionmailer/lib/action_mailer/test_helper.rb
@@ -6,9 +6,9 @@ module ActionMailer
     #
     #   def test_emails
     #     assert_emails 0
-    #     ContactMailer.welcome.deliver
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 1
-    #     ContactMailer.welcome.deliver
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 2
     #   end
     #
@@ -17,12 +17,12 @@ module ActionMailer
     #
     #   def test_emails_again
     #     assert_emails 1 do
-    #       ContactMailer.welcome.deliver
+    #       ContactMailer.welcome.deliver_now
     #     end
     #
     #     assert_emails 2 do
-    #       ContactMailer.welcome.deliver
-    #       ContactMailer.welcome.deliver
+    #       ContactMailer.welcome.deliver_now
+    #       ContactMailer.welcome.deliver_now
     #     end
     #   end
     def assert_emails(number)
@@ -40,7 +40,7 @@ module ActionMailer
     #
     #   def test_emails
     #     assert_no_emails
-    #     ContactMailer.welcome.deliver
+    #     ContactMailer.welcome.deliver_now
     #     assert_emails 1
     #   end
     #