[ci skip] Add a note about headers overwriting

Since some headers can appear multiple times in an email it's required
to set it to nil first when you want to overwrite an existing one.

This commit add some information about this process.

Fix #15912

1 files changed, 21 insertions, 5 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 1ab68d2953..0216185ffa 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -39,11 +39,8 @@ module ActionMailer
   #   in the same manner as <tt>attachments[]=</tt>
   #
   # * <tt>headers[]=</tt> - Allows you to specify any header field in your email such
-  #   as <tt>headers['X-No-Spam'] = 'True'</tt>. Note, while most fields like <tt>To:</tt>
-  #   <tt>From:</tt> can only appear once in an email header, other fields like <tt>X-Anything</tt>
-  #   can appear multiple times. If you want to change a field that can appear multiple times,
-  #   you need to set it to nil first so that Mail knows you are replacing it and not adding
-  #   another field of the same name.
+  #   as <tt>headers['X-No-Spam'] = 'True'</tt>. Note that declaring a header multiple times
+  #   will add many fields of the same name. Read #headers doc for more information.
   #
   # * <tt>headers(hash)</tt> - Allows you to specify multiple headers in your email such
   #   as <tt>headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})</tt>
@@ -625,6 +622,25 @@ module ActionMailer
     # The resulting <tt>Mail::Message</tt> will have the following in its header:
     #
     #   X-Special-Domain-Specific-Header: SecretValue
+    #
+    # Note about replacing already defined headers:
+    #
+    # * +subject+
+    # * +sender+
+    # * +from+
+    # * +to+
+    # * +cc+
+    # * +bcc+
+    # * +reply-to+
+    # * +orig-date+
+    # * +message-id+
+    # * +references+
+    #
+    # fields can only appear once in email headers while other fields such as <tt>X-Anything</tt>
+    # can appear multiple times. If you want to replace any header which already exists,
+    # first set it to nil in order to reset the value otherwise another field will be added
+    # for the same header.
+    #
     def headers(args = nil)
       if args
         @_message.headers(args)