diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index fd7b969496..f822e14cad 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -196,21 +196,59 @@ module ActionMailer #:nodoc:
# the delivery agents. Your object should make and needed modifications directly to the passed
# in Mail::Message instance.
#
+ # = Default Hash
+ #
+ # ActionMailer provides some intelligent defaults for your emails, these are usually specified in a
+ # default method inside the class definition:
+ #
+ # class Notifier < ActionMailer::Base
+ # default :sender => 'system@example.com'
+ # end
+ #
+ # You can pass in any header value that a Mail::Message, out of the box, ActionMailer::Base
+ # sets the following:
+ #
+ # * :mime_version => "1.0"
+ # * :charset => "UTF-8",
+ # * :content_type => "text/plain",
+ # * :parts_order => [ "text/plain", "text/enriched", "text/html" ]
+ #
+ # parts_order and charset are not actually valid Mail::Message header fields,
+ # but ActionMailer translates them appropriately and sets the correct values.
+ #
+ # As you can pass in any header, you need to either quote the header as a string, or pass it in as
+ # an underscorised symbol, so the following will work:
+ #
+ # class Notifier < ActionMailer::Base
+ # default 'Content-Transfer-Encoding' => '7bit',
+ # :content_description => 'This is a description'
+ # end
+ #
+ # Finally, ActionMailer also supports passing Proc objects into the default hash, so you
+ # can define methods that evaluate as the message is being generated:
+ #
+ # class Notifier < ActionMailer::Base
+ # default 'X-Special-Header' => Proc.new { my_method }
+ #
+ # private
+ #
+ # def my_method
+ # 'some complex call'
+ # end
+ # end
+ #
+ # Note that the proc is evaluated right at the start of the mail message generation, so if you
+ # set something in the defaults using a proc, and then set the same thing inside of your
+ # mailer method, it will get over written by the mailer method.
+ #
# = Configuration options
#
- # These options are specified on the class level, like ActionMailer::Base.template_root = "/my/templates"
- #
- # * default - This is a class wide hash of :key => value pairs containing
- # default values for the specified header fields of the Mail::Message. You can
- # specify a default for any valid header for Mail::Message and it will be used if
- # you do not override it. You pass in the header value as a symbol, all lower case with under
- # scores instead of hyphens, so Content-Transfer-Encoding:
- # becomes :content_transfer_encoding. The defaults set by Action Mailer are:
- # * :mime_version => "1.0"
- # * :charset => "UTF-8",
- # * :content_type => "text/plain",
- # * :parts_order => [ "text/plain", "text/enriched", "text/html" ]
+ # These options are specified on the class level, like
+ # ActionMailer::Base.template_root = "/my/templates"
#
+ # * default - You can pass this in at a class level as well as within the class itself as
+ # per the above section.
+ #
# * logger - the logger is used for generating information on the mailing run if available.
# Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
#