Change entire mailers codebase to YARD docs #656

padrino-gen/lib/padrino-gen/generators/components/actions.rb

@@ -15,11 +15,10 @@ module Actions
         #   Additional migration options, e.g { :base => "....text...", :up => "..text...",
         #                                       :down => "..text...", column_format => "t.column :#{field}, :#{kind}" }
         # @example
-        #
-        # output_model_migration("AddPerson", "person", ["name:string", "age:integer"],
-        #      :base => AR_MIGRATION,
-        #      :column_format => Proc.new { |field, kind| "t.#{kind.underscore.gsub(/_/, '')} :#{field}" },
-        #      :up => AR_MODEL_UP_MG, :down => AR_MODEL_DOWN_MG)
+        #   output_model_migration("AddPerson", "person", ["name:string", "age:integer"],
+        #     :base => AR_MIGRATION,
+        #     :column_format => Proc.new { |field, kind| "t.#{kind.underscore.gsub(/_/, '')} :#{field}" },
+        #     :up => AR_MODEL_UP_MG, :down => AR_MODEL_DOWN_MG)
         #
         # @api private
         def output_model_migration(filename, name, columns, options={})

padrino-helpers/lib/padrino-helpers.rb

@@ -32,7 +32,7 @@ class << self
       #   Padrino::Helpers::RenderHelpers
       #   Padrino::Helpers::NumberHelpers
       #
-      # @param [Padrino::Application] app
+      # @param [Sinatra::Application] app
       #   The specified padrino application
       #
       # @example Register the helper module

padrino-mailer/README.rdoc

@@ -91,7 +91,7 @@ is invoking the render function passing the <tt>name</tt> attribute to the body
 
 Once the mailer definition has been completed and the template has been defined, the email can be sent using:
 
-  deliver(:sample, :registration_email, "Bob", "21")
+  deliver(:sample, :registration, "Bob", "21")
 
 And that will then deliver the email according the the configured options. This is all you need to send basic emails.
 

padrino-mailer/lib/padrino-mailer.rb

@@ -1,4 +1,4 @@
-# require tilt if available; fall back on bundled version.
+# requires tilt if available; falls back on bundled version.
 begin
   require 'tilt'
 rescue LoadError
@@ -12,19 +12,38 @@
 
 module Padrino
   ##
-  # This component uses the 'mail' library to create a powerful but simple mailer system within Padrino (and Sinatra).
-  # There is full support for using plain or html content types as well as for attaching files.
-  # The MailerPlugin has many similarities to ActionMailer but is much lighterweight and (arguably) easier to use.
+  # This component uses the +mail+ library to create a powerful but simple mailer within Padrino (and Sinatra).
+  # There is full support for using plain or html content-types as well as for file attachments.
+  #
+  # Using the mailer in Padrino has two forms. The 'quick' method requires only use
+  # of the +email+ method directly in the controller:
+  #
+  #  # app/controllers/session.rb
+  #  post :create do
+  #    email do
+  #      from "tony@reyes.com"
+  #      to "john@smith.com"
+  #      subject "Welcome!"
+  #      body render('email/registered')
+  #    end
+  #  end
+  #
+  # For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
   #
   module Mailer
-    ##
-    # Register
-    #
-    #   Padrino::Mailer::Helpers
-    #
-    # for Padrino::Application
-    #
     class << self
+      ##
+      # Registers the Padrino::Mailer helpers with the application.
+      #
+      # @param [Sinatra::Application] app The application that needs mailers.
+      #
+      # @example
+      #   require 'padrino-mailer'
+      #   class Demo < Padrino::Application
+      #     register Padrino::Mailer::Helpers
+      #   end
+      #
+      # @api public
       def registered(app)
         app.helpers Padrino::Mailer::Helpers
       end

padrino-mailer/lib/padrino-mailer/base.rb

@@ -5,28 +5,58 @@ module Mailer
     #
     # You can set the default delivery settings from your app through:
     #
-    #   set :delivery_method, :smtp => {
-    #     :address         => 'smtp.yourserver.com',
-    #     :port            => '25',
-    #     :user_name       => 'user',
-    #     :password        => 'pass',
-    #     :authentication  => :plain # :plain, :login, :cram_md5, no auth by default
-    #     :domain          => "localhost.localdomain" # the HELO domain provided by the client to the server
-    #   }
+    #  set :delivery_method, :smtp => {
+    #    :address         => 'smtp.yourserver.com',
+    #    :port            => '25',
+    #    :user_name       => 'user',
+    #    :password        => 'pass',
+    #    :authentication  => :plain
+    #  }
     #
     # or sendmail:
     #
-    #   set :delivery_method, :sendmail
+    #  set :delivery_method, :sendmail
     #
     # or for tests:
     #
-    #   set :delivery_method, :test
+    #  set :delivery_method, :test
     #
-    # and then all delivered mail will use these settings unless otherwise specified.
+    # and all delivered mail will use these settings unless otherwise specified.
+    #
+    # Define a mailer in your application:
+    #
+    #   # app/mailers/sample_mailer.rb
+    #   MyAppName.mailers :sample do
+    #     defaults :content_type => 'html'
+    #     email :registration do |name, age|
+    #       to      'user@domain.com'
+    #       from    'admin@site.com'
+    #       subject 'Welcome to the site!'
+    #       locals  :name => name
+    #       render  'registration'
+    #     end
+    #   end
+    #
+    # Use the mailer to deliver messages:
+    #
+    #  deliver(:sample, :registration, "Bob", "21")
+    #
+    # For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
     #
     class Base
       attr_accessor :delivery_settings, :app, :mailer_name, :messages
 
+      # Constructs a +Mailer+ base object with specified options.
+      #
+      # @param [Sinatra::Application] app
+      #   The application tied to this mailer.
+      # @param [Symbol] name
+      #   The name of this mailer.
+      # @param [Proc] block
+      #   The +email+ definitions block.
+      #
+      # @see Padrino::Mailer::Helpers::ClassMethods#mailer
+      # @api private
       def initialize(app, name, &block) # @private
         @mailer_name = name
         @messages    = {}
@@ -38,8 +68,12 @@ def initialize(app, name, &block) # @private
       ##
       # Defines a mailer object allowing the definition of various email messages that can be delivered
       #
-      # ==== Examples
+      # @param [Symbol] name
+      #   The name of this email message.
+      # @param [Proc] block
+      #   The message definition (i.e subject, to, from, locals).
       #
+      # @example
       #   email :birthday do |name, age|
       #     subject "Happy Birthday!"
       #     to   'john@fake.com'
@@ -48,6 +82,7 @@ def initialize(app, name, &block) # @private
       #     render 'birthday'
       #   end
       #
+      # @api public
       def email(name, &block)
         raise "The email '#{name}' is already defined" if self.messages[name].present?
         self.messages[name] = Proc.new { |*attrs|
@@ -62,13 +97,16 @@ def email(name, &block)
 
       # Defines the default attributes for a message in this mailer (including app-wide defaults)
       #
-      # ==== Examples
+      # @param [Hash] attributes
+      #   The hash of message options to use as default.
       #
+      # @example
       #   mailer :alternate do
-      #    defaults :from => 'padrino@from.com', :to => 'padrino@to.com'
-      #    email(:foo) do ... end
+      #     defaults :from => 'padrino@from.com', :to => 'padrino@to.com'
+      #     email(:foo) do; end
       #   end
       #
+      # @api public
       def defaults(attributes=nil)
         if attributes.nil? # Retrieve the default values
           @app.respond_to?(:mailer_defaults) ? @app.mailer_defaults.merge(@defaults) : @defaults

padrino-mailer/lib/padrino-mailer/ext.rb

@@ -25,8 +25,7 @@ def initialize_with_app(*args, &block)
     ##
     # Setup like in Sinatra/Padrino apps content_type and template lookup.
     #
-    # ==== Examples
-    #
+    # @example
     #   # This add a email plain part if a template called bar.plain.* is found
     #   # and a html part if a template called bar.html.* is found
     #   email do
@@ -50,8 +49,7 @@ def provides(*formats)
     # html_part are both defined in a message, then it will be a multipart/alternative
     # message and set itself that way.
     #
-    # ==== Examples
-    #
+    # @example
     #  text_part "Some text"
     #  text_part { render('multipart/basic.text') }
     #
@@ -69,8 +67,7 @@ def text_part(value=nil, &block)
     # text_part are both defined in a message, then it will be a multipart/alternative
     # message and set itself that way.
     #
-    # ==== Examples
-    #
+    # @example
     #  html_part "Some <b>Html</b> text"
     #  html_part { render('multipart/basic.html') }
     #
@@ -86,8 +83,7 @@ def html_part(value=nil, &block)
     ##
     # Allows you to add a part in block form to an existing mail message object
     #
-    # ==== Examples
-    #
+    # @example
     #  mail = Mail.new do
     #    part :content_type => "multipart/alternative", :content_disposition => "inline" do |p|
     #      p.part :content_type => "text/plain", :body => "test text\nline #2"

padrino-mailer/lib/padrino-mailer/helpers.rb

@@ -6,10 +6,14 @@ def self.included(base) # @private
       end
 
       ##
-      # Delivers an email with the given mail attributes (to, from, subject, cc, bcc, body, et.al)
+      # Delivers an email with the given mail attributes.
       #
-      # ==== Examples
+      # @param [Hash] mail_attributes
+      #   The attributes for this message (to, from, subject, cc, bcc, body, etc)
+      # @param [Proc] block
+      #   The block mail attributes for this message.
       #
+      # @example
       #   email do
       #     to      @user.email
       #     from    "awesomeness@example.com"
@@ -18,18 +22,28 @@ def self.included(base) # @private
       #     render  'path/to/my/template'
       #   end
       #
+      # @see ClassMethods#email
+      # @api public
       def email(mail_attributes={}, &block)
         settings.email(mail_attributes, &block)
       end
 
       ##
-      # Delivers a mailer message email with the given attributes
+      # Delivers a mailer message email with the given attributes.
       #
-      # ==== Examples
+      # @param [Symbol] mailer_name
+      #   The name of the mailer.
+      # @param [Symbol] message_name
+      #   The name of the message to deliver.
+      # @param attributes
+      #   The parameters to pass to the mailer.
       #
+      # @example
       #   deliver(:sample, :birthday, "Joey", 21)
       #   deliver(:example, :message, "John")
       #
+      # @see ClassMethods#deliver
+      # @api public
       def deliver(mailer_name, message_name, *attributes)
         settings.deliver(mailer_name, message_name, *attributes)
       end
@@ -42,16 +56,18 @@ def inherited(subclass) # @private
 
         ##
         # Returns all registered mailers for this application
-        #
+        # @private
         def registered_mailers
           @_registered_mailers ||= {}
         end
 
         ##
-        # Defines a mailer object allowing the definition of various email messages that can be delivered
+        # Defines a mailer object allowing the definition of various email messages that can be delivered.
         #
-        # ==== Examples
+        # @param [Symbol] name
+        #   The name of the mailer to initialize.
         #
+        # @example
         #   mailer :sample do
         #     email :birthday do |name, age|
         #       subject 'Happy Birthday!'
@@ -62,6 +78,7 @@ def registered_mailers
         #     end
         #   end
         #
+        # @api public
         def mailer(name, &block)
           mailer                   = Padrino::Mailer::Base.new(self, name, &block)
           mailer.delivery_settings = delivery_settings
@@ -73,23 +90,33 @@ def mailer(name, &block)
         ##
         # Delivers a mailer message email with the given attributes
         #
-        # ==== Examples
+        # @param [Symbol] mailer_name
+        #   The name of the mailer.
+        # @param [Symbol] message_name
+        #   The name of the message to deliver.
+        # @param attributes
+        #   The parameters to pass to the mailer.
         #
+        # @example
         #   deliver(:sample, :birthday, "Joey", 21)
         #   deliver(:example, :message, "John")
         #
+        # @api public
         def deliver(mailer_name, message_name, *attributes)
           message = registered_mailers[mailer_name].messages[message_name].call(*attributes)
           message.delivery_method(*delivery_settings)
           message.deliver
         end
 
         ##
-        # Delivers an email with the given mail attributes (to, from, subject, cc, bcc, body, et.al) using settings of
-        # the given app.
+        # Delivers an email with the given mail attributes with specified and default settings.
         #
-        # ==== Examples
+        # @param [Hash] mail_attributes
+        #   The attributes for this message (to, from, subject, cc, bcc, body, etc)
+        # @param [Proc] block
+        #   The block mail attributes for this message.
         #
+        # @example
         #   MyApp.email(:to => 'to@ma.il', :from => 'from@ma.il', :subject => 'Welcome!', :body => 'Welcome Here!')
         #
         #   # or if you prefer blocks
@@ -101,6 +128,7 @@ def deliver(mailer_name, message_name, *attributes)
         #     body 'path/to/my/template', :locals => { :a => a, :b => b }
         #   end
         #
+        # @api public
         def email(mail_attributes={}, &block)
           message = Mail::Message.new(self)
           message.delivery_method(*delivery_settings)
@@ -111,7 +139,7 @@ def email(mail_attributes={}, &block)
 
         private
           ##
-          # Return the parsed delivery method
+          # Returns the parsed delivery method options
           #
           def delivery_settings
             @_delivery_setting ||= begin