Update/extend ActionMailer documentation (rdoc)

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2648 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

6 files changed, 128 insertions, 16 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 699714c78f..a77f9ce018 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -4,7 +4,7 @@ require 'action_mailer/part_container'
 require 'action_mailer/utils'
 require 'tmail/net'
 
-module ActionMailer #:nodoc:
+module ActionMailer
   # Usage:
   #
   #   class ApplicationMailer < ActionMailer::Base
@@ -160,11 +160,61 @@ module ActionMailer #:nodoc:
     @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ]
     cattr_accessor :default_implicit_parts_order
 
-    adv_attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers,
-                      :bcc, :cc, :charset, :content_type, :implicit_parts_order,
-                      :template, :mailer_name, :mime_version
+    # Specify the BCC addresses for the message
+    adv_attr_accessor :bcc
+    
+    # Define the body of the message. This is either a Hash (in which case it
+    # specifies the variables to pass to the template when it is rendered),
+    # or a string, in which case it specifies the actual text of the message.
+    adv_attr_accessor :body
+    
+    # Specify the CC addresses for the message.
+    adv_attr_accessor :cc
+    
+    # Specify the charset to use for the message. This defaults to the
+    # +default_charset+ specified for ActionMailer::Base.
+    adv_attr_accessor :charset
+    
+    # Specify the content type for the message. This defaults to <tt>text/plain</tt>
+    # in most cases, but can be automatically set in some situations.
+    adv_attr_accessor :content_type
+    
+    # Specify the from address for the message.
+    adv_attr_accessor :from
+    
+    # Specify additional headers to be added to the message.
+    adv_attr_accessor :headers
+    
+    # Specify the order in which parts should be sorted, based on content-type.
+    # This defaults to the value for the +default_implicit_parts_order+.
+    adv_attr_accessor :implicit_parts_order
+    
+    # Override the mailer name, which defaults to an inflected version of the
+    # mailer's class name. If you want to use a template in a non-standard
+    # location, you can use this to specify that location.
+    adv_attr_accessor :mailer_name
+    
+    # Defaults to "1.0", but may be explicitly given if needed.
+    adv_attr_accessor :mime_version
+    
+    # The recipient addresses for the message, either as a string (for a single
+    # address) or an array (for multiple addresses).
+    adv_attr_accessor :recipients
+    
+    # The date on which the message was sent. If not set (the default), the
+    # header will be set by the delivery agent.
+    adv_attr_accessor :sent_on
+    
+    # Specify the subject of the message.
+    adv_attr_accessor :subject
+    
+    # Specify the template name to use for current message. This is the "base"
+    # template name, without the extension or directory, and may be used to
+    # have multiple mailer methods share the same template.
+    adv_attr_accessor :template
 
-    attr_reader       :mail
+    # The mail object instance referenced by this mailer.
+    attr_reader :mail
 
     class << self
       def method_missing(method_symbol, *parameters)#:nodoc:
@@ -176,7 +226,18 @@ module ActionMailer #:nodoc:
         end
       end
 
-      def receive(raw_email) #:nodoc:
+      # Receives a raw email, parses it into an email object, decodes it,
+      # instantiates a new mailer, and passes the email object to the mailer
+      # object's #receive method. If you want your mailer to be able to
+      # process incoming messages, you'll need to implement a #receive
+      # method that accepts the email object as a parameter:
+      #
+      #   class MyMailer < ActionMailer::Base
+      #     def receive(mail)
+      #       ...
+      #     end
+      #   end
+      def receive(raw_email)
         logger.info "Received mail:\n #{raw_email}" unless logger.nil?
         mail = TMail::Mail.parse(raw_email)
         mail.base64_decode
@@ -258,7 +319,7 @@ module ActionMailer #:nodoc:
     # Delivers a TMail::Mail object. By default, it delivers the cached mail
     # object (from the #create! method). If no cached mail object exists, and
     # no alternate has been given as the parameter, this will fail.
-    def deliver!(mail = @mail) #:nodoc:
+    def deliver!(mail = @mail)
       raise "no mail object available for delivery!" unless mail
       logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
 
diff --git a/actionmailer/lib/action_mailer/helpers.rb b/actionmailer/lib/action_mailer/helpers.rb
index f482758386..b53326ca72 100644
--- a/actionmailer/lib/action_mailer/helpers.rb
+++ b/actionmailer/lib/action_mailer/helpers.rb
@@ -1,6 +1,6 @@
-module ActionMailer #:nodoc:
+module ActionMailer
   module Helpers #:nodoc:
-    def self.append_features(base)
+    def self.append_features(base) #:nodoc:
       super
 
       # Initialize the base module to aggregate its helpers.
@@ -24,7 +24,7 @@ module ActionMailer #:nodoc:
       end
     end
 
-    module ClassMethods #:nodoc:
+    module ClassMethods
       # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
       # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules 
       # available to the templates.
diff --git a/actionmailer/lib/action_mailer/mail_helper.rb b/actionmailer/lib/action_mailer/mail_helper.rb
index 9c7370065f..11fd7d77e0 100644
--- a/actionmailer/lib/action_mailer/mail_helper.rb
+++ b/actionmailer/lib/action_mailer/mail_helper.rb
@@ -1,6 +1,8 @@
 require 'text/format'
 
-module MailHelper#:nodoc:
+module MailHelper
+  # Uses Text::Format to take the text and format it, indented two spaces for
+  # each line, and wrapped at 72 columns.
   def block_format(text)
     formatted = text.split(/\n\r\n/).collect { |paragraph| 
       Text::Format.new(
diff --git a/actionmailer/lib/action_mailer/part.rb b/actionmailer/lib/action_mailer/part.rb
index d4b8e3b9d9..0036d04da0 100644
--- a/actionmailer/lib/action_mailer/part.rb
+++ b/actionmailer/lib/action_mailer/part.rb
@@ -3,13 +3,43 @@ require 'action_mailer/part_container'
 require 'action_mailer/utils'
 
 module ActionMailer
-  class Part #:nodoc:
+  # Represents a subpart of an email message. It shares many similar
+  # attributes of ActionMailer::Base.  Although you can create parts manually
+  # and add them to the #parts list of the mailer, it is easier
+  # to use the helper methods in ActionMailer::PartContainer.
+  class Part
     include ActionMailer::AdvAttrAccessor
     include ActionMailer::PartContainer
 
-    adv_attr_accessor :content_type, :content_disposition, :charset, :body
-    adv_attr_accessor :filename, :transfer_encoding, :headers
+    # Represents the body of the part, as a string. This should not be a
+    # Hash (like ActionMailer::Base), but if you want a template to be rendered
+    # into the body of a subpart you can do it with the mailer's #render method
+    # and assign the result here.
+    adv_attr_accessor :body
+    
+    # Specify the charset for this subpart. By default, it will be the charset
+    # of the containing part or mailer.
+    adv_attr_accessor :charset
+    
+    # The content disposition of this part, typically either "inline" or
+    # "attachment".
+    adv_attr_accessor :content_disposition
+    
+    # The content type of the part.
+    adv_attr_accessor :content_type
+    
+    # The filename to use for this subpart (usually for attachments).
+    adv_attr_accessor :filename
+    
+    # Accessor for specifying additional headers to include with this part.
+    adv_attr_accessor :headers
+    
+    # The transfer encoding to use for this subpart, like "base64" or
+    # "quoted-printable".
+    adv_attr_accessor :transfer_encoding
 
+    # Create a new part from the given +params+ hash. The valid params keys
+    # correspond to the accessors.
     def initialize(params)
       @content_type = params[:content_type]
       @content_disposition = params[:disposition] || "inline"
@@ -21,6 +51,8 @@ module ActionMailer
       @parts = []
     end
 
+    # Convert the part to a mail object which can be included in the parts
+    # list of another mail object.
     def to_mail(defaults)
       part = TMail::Mail.new
 
diff --git a/actionmailer/lib/action_mailer/part_container.rb b/actionmailer/lib/action_mailer/part_container.rb
index 7a69efeb49..9cbdd35497 100644
--- a/actionmailer/lib/action_mailer/part_container.rb
+++ b/actionmailer/lib/action_mailer/part_container.rb
@@ -1,5 +1,22 @@
 module ActionMailer
-  module PartContainer #:nodoc:
+  # Accessors and helpers that ActionMailer::Base and ActionMailer::Part have
+  # in common. Using these helpers you can easily add subparts or attachments
+  # to your message:
+  #
+  #   def my_mail_message(...)
+  #     ...
+  #     part "text/plain" do |p|
+  #       p.body "hello, world"
+  #       p.transfer_encoding "base64"
+  #     end
+  #
+  #     attachment "image/jpg" do |a|
+  #       a.body = File.read("hello.jpg")
+  #       a.filename = "hello.jpg"
+  #     end
+  #   end
+  module PartContainer
+    # The list of subparts of this container
     attr_reader :parts
 
     # Add a part to a multipart message, with the given content-type. The
diff --git a/actionmailer/lib/action_mailer/version.rb b/actionmailer/lib/action_mailer/version.rb
index 557b05f14e..2108ffb282 100644
--- a/actionmailer/lib/action_mailer/version.rb
+++ b/actionmailer/lib/action_mailer/version.rb
@@ -1,5 +1,5 @@
 module ActionMailer
-  module Version
+  module Version #:nodoc:
     MAJOR = 1
     MINOR = 0
     TINY  = 1