Skip to content
This repository
Browse code

Update/extend ActionMailer documentation (rdoc)

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2648 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 59f1df1b5b37a9e16a6b03d931c7b620075034d5 1 parent 0453525
Jamis Buck authored October 16, 2005
2  actionmailer/CHANGELOG
... ...
@@ -1,5 +1,7 @@
1 1
 *SVN*
2 2
 
  3
+* Update and extend documentation (rdoc)
  4
+
3 5
 * Minero Aoki made TMail available to Rails/ActionMailer under the MIT license (instead of LGPL) [RubyConf '05]
4 6
 
5 7
 * Austin Ziegler made Text::Simple available to Rails/ActionMailer under a MIT-like licens [See rails ML, subject "Text::Format Licence Exception" on Oct 15, 2005]
2  actionmailer/Rakefile
@@ -32,7 +32,7 @@ Rake::TestTask.new { |t|
32 32
 Rake::RDocTask.new { |rdoc|
33 33
   rdoc.rdoc_dir = 'doc'
34 34
   rdoc.title    = "Action Mailer -- Easy email delivery and testing"
35  
-  rdoc.options << '--line-numbers --inline-source --main README'
  35
+  rdoc.options << '--line-numbers --inline-source --main README --accessor adv_attr_accessor=M'
36 36
   rdoc.template = "#{ENV['template']}.rb" if ENV['template']
37 37
   rdoc.rdoc_files.include('README', 'CHANGELOG')
38 38
   rdoc.rdoc_files.include('lib/action_mailer.rb')
75  actionmailer/lib/action_mailer/base.rb
@@ -4,7 +4,7 @@
4 4
 require 'action_mailer/utils'
5 5
 require 'tmail/net'
6 6
 
7  
-module ActionMailer #:nodoc:
  7
+module ActionMailer
8 8
   # Usage:
9 9
   #
10 10
   #   class ApplicationMailer < ActionMailer::Base
@@ -160,11 +160,61 @@ class Base
160 160
     @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ]
161 161
     cattr_accessor :default_implicit_parts_order
162 162
 
163  
-    adv_attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers,
164  
-                      :bcc, :cc, :charset, :content_type, :implicit_parts_order,
165  
-                      :template, :mailer_name, :mime_version
  163
+    # Specify the BCC addresses for the message
  164
+    adv_attr_accessor :bcc
  165
+    
  166
+    # Define the body of the message. This is either a Hash (in which case it
  167
+    # specifies the variables to pass to the template when it is rendered),
  168
+    # or a string, in which case it specifies the actual text of the message.
  169
+    adv_attr_accessor :body
  170
+    
  171
+    # Specify the CC addresses for the message.
  172
+    adv_attr_accessor :cc
  173
+    
  174
+    # Specify the charset to use for the message. This defaults to the
  175
+    # +default_charset+ specified for ActionMailer::Base.
  176
+    adv_attr_accessor :charset
  177
+    
  178
+    # Specify the content type for the message. This defaults to <tt>text/plain</tt>
  179
+    # in most cases, but can be automatically set in some situations.
  180
+    adv_attr_accessor :content_type
  181
+    
  182
+    # Specify the from address for the message.
  183
+    adv_attr_accessor :from
  184
+    
  185
+    # Specify additional headers to be added to the message.
  186
+    adv_attr_accessor :headers
  187
+    
  188
+    # Specify the order in which parts should be sorted, based on content-type.
  189
+    # This defaults to the value for the +default_implicit_parts_order+.
  190
+    adv_attr_accessor :implicit_parts_order
  191
+    
  192
+    # Override the mailer name, which defaults to an inflected version of the
  193
+    # mailer's class name. If you want to use a template in a non-standard
  194
+    # location, you can use this to specify that location.
  195
+    adv_attr_accessor :mailer_name
  196
+    
  197
+    # Defaults to "1.0", but may be explicitly given if needed.
  198
+    adv_attr_accessor :mime_version
  199
+    
  200
+    # The recipient addresses for the message, either as a string (for a single
  201
+    # address) or an array (for multiple addresses).
  202
+    adv_attr_accessor :recipients
  203
+    
  204
+    # The date on which the message was sent. If not set (the default), the
  205
+    # header will be set by the delivery agent.
  206
+    adv_attr_accessor :sent_on
  207
+    
  208
+    # Specify the subject of the message.
  209
+    adv_attr_accessor :subject
  210
+    
  211
+    # Specify the template name to use for current message. This is the "base"
  212
+    # template name, without the extension or directory, and may be used to
  213
+    # have multiple mailer methods share the same template.
  214
+    adv_attr_accessor :template
166 215
 
167  
-    attr_reader       :mail
  216
+    # The mail object instance referenced by this mailer.
  217
+    attr_reader :mail
168 218
 
169 219
     class << self
170 220
       def method_missing(method_symbol, *parameters)#:nodoc:
@@ -176,7 +226,18 @@ def method_missing(method_symbol, *parameters)#:nodoc:
176 226
         end
177 227
       end
178 228
 
179  
-      def receive(raw_email) #:nodoc:
  229
+      # Receives a raw email, parses it into an email object, decodes it,
  230
+      # instantiates a new mailer, and passes the email object to the mailer
  231
+      # object's #receive method. If you want your mailer to be able to
  232
+      # process incoming messages, you'll need to implement a #receive
  233
+      # method that accepts the email object as a parameter:
  234
+      #
  235
+      #   class MyMailer < ActionMailer::Base
  236
+      #     def receive(mail)
  237
+      #       ...
  238
+      #     end
  239
+      #   end
  240
+      def receive(raw_email)
180 241
         logger.info "Received mail:\n #{raw_email}" unless logger.nil?
181 242
         mail = TMail::Mail.parse(raw_email)
182 243
         mail.base64_decode
@@ -258,7 +319,7 @@ def create!(method_name, *parameters) #:nodoc:
258 319
     # Delivers a TMail::Mail object. By default, it delivers the cached mail
259 320
     # object (from the #create! method). If no cached mail object exists, and
260 321
     # no alternate has been given as the parameter, this will fail.
261  
-    def deliver!(mail = @mail) #:nodoc:
  322
+    def deliver!(mail = @mail)
262 323
       raise "no mail object available for delivery!" unless mail
263 324
       logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
264 325
 
6  actionmailer/lib/action_mailer/helpers.rb
... ...
@@ -1,6 +1,6 @@
1  
-module ActionMailer #:nodoc:
  1
+module ActionMailer
2 2
   module Helpers #:nodoc:
3  
-    def self.append_features(base)
  3
+    def self.append_features(base) #:nodoc:
4 4
       super
5 5
 
6 6
       # Initialize the base module to aggregate its helpers.
@@ -24,7 +24,7 @@ class << self
24 24
       end
25 25
     end
26 26
 
27  
-    module ClassMethods #:nodoc:
  27
+    module ClassMethods
28 28
       # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
29 29
       # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules 
30 30
       # available to the templates.
4  actionmailer/lib/action_mailer/mail_helper.rb
... ...
@@ -1,6 +1,8 @@
1 1
 require 'text/format'
2 2
 
3  
-module MailHelper#:nodoc:
  3
+module MailHelper
  4
+  # Uses Text::Format to take the text and format it, indented two spaces for
  5
+  # each line, and wrapped at 72 columns.
4 6
   def block_format(text)
5 7
     formatted = text.split(/\n\r\n/).collect { |paragraph| 
6 8
       Text::Format.new(
38  actionmailer/lib/action_mailer/part.rb
@@ -3,13 +3,43 @@
3 3
 require 'action_mailer/utils'
4 4
 
5 5
 module ActionMailer
6  
-  class Part #:nodoc:
  6
+  # Represents a subpart of an email message. It shares many similar
  7
+  # attributes of ActionMailer::Base.  Although you can create parts manually
  8
+  # and add them to the #parts list of the mailer, it is easier
  9
+  # to use the helper methods in ActionMailer::PartContainer.
  10
+  class Part
7 11
     include ActionMailer::AdvAttrAccessor
8 12
     include ActionMailer::PartContainer
9 13
 
10  
-    adv_attr_accessor :content_type, :content_disposition, :charset, :body
11  
-    adv_attr_accessor :filename, :transfer_encoding, :headers
  14
+    # Represents the body of the part, as a string. This should not be a
  15
+    # Hash (like ActionMailer::Base), but if you want a template to be rendered
  16
+    # into the body of a subpart you can do it with the mailer's #render method
  17
+    # and assign the result here.
  18
+    adv_attr_accessor :body
  19
+    
  20
+    # Specify the charset for this subpart. By default, it will be the charset
  21
+    # of the containing part or mailer.
  22
+    adv_attr_accessor :charset
  23
+    
  24
+    # The content disposition of this part, typically either "inline" or
  25
+    # "attachment".
  26
+    adv_attr_accessor :content_disposition
  27
+    
  28
+    # The content type of the part.
  29
+    adv_attr_accessor :content_type
  30
+    
  31
+    # The filename to use for this subpart (usually for attachments).
  32
+    adv_attr_accessor :filename
  33
+    
  34
+    # Accessor for specifying additional headers to include with this part.
  35
+    adv_attr_accessor :headers
  36
+    
  37
+    # The transfer encoding to use for this subpart, like "base64" or
  38
+    # "quoted-printable".
  39
+    adv_attr_accessor :transfer_encoding
12 40
 
  41
+    # Create a new part from the given +params+ hash. The valid params keys
  42
+    # correspond to the accessors.
13 43
     def initialize(params)
14 44
       @content_type = params[:content_type]
15 45
       @content_disposition = params[:disposition] || "inline"
@@ -21,6 +51,8 @@ def initialize(params)
21 51
       @parts = []
22 52
     end
23 53
 
  54
+    # Convert the part to a mail object which can be included in the parts
  55
+    # list of another mail object.
24 56
     def to_mail(defaults)
25 57
       part = TMail::Mail.new
26 58
 
19  actionmailer/lib/action_mailer/part_container.rb
... ...
@@ -1,5 +1,22 @@
1 1
 module ActionMailer
2  
-  module PartContainer #:nodoc:
  2
+  # Accessors and helpers that ActionMailer::Base and ActionMailer::Part have
  3
+  # in common. Using these helpers you can easily add subparts or attachments
  4
+  # to your message:
  5
+  #
  6
+  #   def my_mail_message(...)
  7
+  #     ...
  8
+  #     part "text/plain" do |p|
  9
+  #       p.body "hello, world"
  10
+  #       p.transfer_encoding "base64"
  11
+  #     end
  12
+  #
  13
+  #     attachment "image/jpg" do |a|
  14
+  #       a.body = File.read("hello.jpg")
  15
+  #       a.filename = "hello.jpg"
  16
+  #     end
  17
+  #   end
  18
+  module PartContainer
  19
+    # The list of subparts of this container
3 20
     attr_reader :parts
4 21
 
5 22
     # Add a part to a multipart message, with the given content-type. The
2  actionmailer/lib/action_mailer/version.rb
... ...
@@ -1,5 +1,5 @@
1 1
 module ActionMailer
2  
-  module Version
  2
+  module Version #:nodoc:
3 3
     MAJOR = 1
4 4
     MINOR = 0
5 5
     TINY  = 1

0 notes on commit 59f1df1

Please sign in to comment.
Something went wrong with that request. Please try again.