Merge branch 'master' of git://github.com/lifo/docrails

actionpack/lib/action_controller/caching/pages.rb

@@ -16,9 +16,10 @@ module Caching
     #     caches_page :show, :new
     #   end
     #
-    # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>,
-    # which match the URLs used to trigger the dynamic generation. This is how the web server is able
-    # pick up a cache file when it exists and otherwise let the request pass on to Action Pack to generate it.
+    # This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>, which match the URLs used 
+    # that would normally trigger dynamic page generation. Page caching works by configuring a web server to first check for the
+    # existence of files on disk, and to serve them directly when found, without passing the request through to Action Pack.
+    # This is much faster than handling the full dynamic request in the usual way.
     #
     # Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache
     # is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
@@ -132,8 +133,8 @@ def expire_page(options = {})
         end
       end
 
-      # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used
-      # If no options are provided, the requested url is used. Example:
+      # Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used.
+      # If no options are provided, the url of the current request being handled is used. Example:
       #   cache_page "I'm the cached content", :controller => "lists", :action => "show"
       def cache_page(content = nil, options = nil)
         return unless self.class.perform_caching && caching_allowed?

actionpack/lib/action_controller/metal/request_forgery_protection.rb

@@ -7,17 +7,16 @@ class InvalidAuthenticityToken < ActionControllerError #:nodoc:
   # Controller actions are protected from Cross-Site Request Forgery (CSRF) attacks
   # by including a token in the rendered html for your application. This token is
   # stored as a random string in the session, to which an attacker does not have
-  # access. When a request reaches your application, \Rails then verifies the received
-  # token with the token in the session. Only HTML and javascript requests are checked,
+  # access. When a request reaches your application, \Rails verifies the received
+  # token with the token in the session. Only HTML and JavaScript requests are checked,
   # so this will not protect your XML API (presumably you'll have a different
   # authentication scheme there anyway). Also, GET requests are not protected as these
   # should be idempotent.
   #
   # CSRF protection is turned on with the <tt>protect_from_forgery</tt> method,
-  # which will check the token and raise an ActionController::InvalidAuthenticityToken
-  # if it doesn't match what was expected. A call to this method is generated for new
-  # \Rails applications by default. You can customize the error message by editing
-  # public/422.html.
+  # which checks the token and resets the session if it doesn't match what was expected.
+  # A call to this method is generated for new \Rails applications by default.
+  # You can customize the error message by editing public/422.html.
   #
   # The token parameter is named <tt>authenticity_token</tt> by default. The name and
   # value of this token must be added to every layout that renders forms by including
@@ -79,6 +78,8 @@ def verify_authenticity_token
         end
       end
 
+      # This is the method that defines the application behaviour when a request is found to be unverified.
+      # By default, \Rails resets the session when it finds an unverified request.
       def handle_unverified_request
         reset_session
       end

activerecord/lib/active_record/migration.rb

@@ -66,9 +66,9 @@ def initialize(name)
   #       create_table :system_settings do |t|
   #         t.string  :name
   #         t.string  :label
-  #         t.text  :value
+  #         t.text    :value
   #         t.string  :type
-  #         t.integer  :position
+  #         t.integer :position
   #       end
   #
   #       SystemSetting.create  :name => "notice",
@@ -181,7 +181,7 @@ def initialize(name)
   #
   #   class RemoveEmptyTags < ActiveRecord::Migration
   #     def up
-  #       Tag.find(:all).each { |tag| tag.destroy if tag.pages.empty? }
+  #       Tag.all.each { |tag| tag.destroy if tag.pages.empty? }
   #     end
   #
   #     def down
@@ -227,7 +227,7 @@ def initialize(name)
   #     def up
   #       add_column :people, :salary, :integer
   #       Person.reset_column_information
-  #       Person.find(:all).each do |p|
+  #       Person.all.each do |p|
   #         p.update_attribute :salary, SalaryCalculator.compute(p)
   #       end
   #     end
@@ -247,7 +247,7 @@ def initialize(name)
   #   def up
   #     ...
   #     say_with_time "Updating salaries..." do
-  #       Person.find(:all).each do |p|
+  #       Person.all.each do |p|
   #         p.update_attribute :salary, SalaryCalculator.compute(p)
   #       end
   #     end

activerecord/lib/active_record/migration/command_recorder.rb

@@ -6,7 +6,7 @@ class Migration
     #
     # * add_column
     # * add_index
-    # * add_timestamp
+    # * add_timestamps
     # * create_table
     # * remove_timestamps
     # * rename_column

activesupport/lib/active_support/benchmarkable.rb

@@ -3,28 +3,28 @@
 
 module ActiveSupport
   module Benchmarkable
-    # Allows you to measure the execution time of a block
-    # in a template and records the result to the log. Wrap this block around
-    # expensive operations or possible bottlenecks to get a time reading
-    # for the operation. For example, let's say you thought your file
-    # processing method was taking too long; you could wrap it in a benchmark block.
+    # Allows you to measure the execution time of a block in a template and records the result to
+    # the log. Wrap this block around expensive operations or possible bottlenecks to get a time
+    # reading for the operation. For example, let's say you thought your file processing method
+    # was taking too long; you could wrap it in a benchmark block.
     #
     #  <% benchmark "Process data files" do %>
     #    <%= expensive_files_operation %>
     #  <% end %>
     #
-    # That would add something like "Process data files (345.2ms)" to the log,
-    # which you can then use to compare timings when optimizing your code.
+    # That would add something like "Process data files (345.2ms)" to the log, which you can then
+    # use to compare timings when optimizing your code.
     #
-    # You may give an optional logger level as the :level option.
-    # (:debug, :info, :warn, :error); the default value is :info.
+    # You may give an optional logger level (:debug, :info, :warn, :error) as the :level option.
+    # The default logger level value is :info.
     #
     #  <% benchmark "Low-level files", :level => :debug do %>
     #    <%= lowlevel_files_operation %>
     #  <% end %>
     #
-    # Finally, you can pass true as the third argument to silence all log activity
-    # inside the block. This is great for boiling down a noisy block to just a single statement:
+    # Finally, you can pass true as the third argument to silence all log activity (other than the
+    # timing information) from inside the block. This is great for boiling down a noisy block to 
+    # just a single statement that produces one log line:
     #
     #  <% benchmark "Process data files", :level => :info, :silence => true do %>
     #    <%= expensive_and_chatty_files_operation %>

activesupport/lib/active_support/cache.rb

@@ -116,31 +116,32 @@ def self.expand_cache_key(key, namespace = nil)
     #   cache.read("city")   # => "Duckburgh"
     #
     # Keys are always translated into Strings and are case sensitive. When an
-    # object is specified as a key, its +cache_key+ method will be called if it
-    # is defined. Otherwise, the +to_param+ method will be called. Hashes and
-    # Arrays can be used as keys. The elements will be delimited by slashes
-    # and Hashes elements will be sorted by key so they are consistent.
+    # object is specified as a key and has a +cache_key+ method defined, this
+    # method will be called to define the key.  Otherwise, the +to_param+
+    # method will be called. Hashes and Arrays can also be used as keys. The
+    # elements will be delimited by slashes, and the elements within a Hash
+    # will be sorted by key so they are consistent.
     #
     #   cache.read("city") == cache.read(:city)   # => true
     #
     # Nil values can be cached.
     #
-    # If your cache is on a shared infrastructure, you can define a namespace for
-    # your cache entries. If a namespace is defined, it will be prefixed on to every
-    # key. The namespace can be either a static value or a Proc. If it is a Proc, it
-    # will be invoked when each key is evaluated so that you can use application logic
-    # to invalidate keys.
+    # If your cache is on a shared infrastructure, you can define a namespace
+    # for your cache entries. If a namespace is defined, it will be prefixed on
+    # to every key. The namespace can be either a static value or a Proc. If it
+    # is a Proc, it will be invoked when each key is evaluated so that you can
+    # use application logic to invalidate keys.
     #
     #   cache.namespace = lambda { @last_mod_time }  # Set the namespace to a variable
     #   @last_mod_time = Time.now  # Invalidate the entire cache by changing namespace
     #
     #
-    # Caches can also store values in a compressed format to save space and reduce
-    # time spent sending data. Since there is some overhead, values must be large
-    # enough to warrant compression. To turn on compression either pass
-    # <tt>:compress => true</tt> in the initializer or to +fetch+ or +write+.
-    # To specify the threshold at which to compress values, set
-    # <tt>:compress_threshold</tt>. The default threshold is 32K.
+    # Caches can also store values in a compressed format to save space and
+    # reduce time spent sending data. Since there is overhead, values must be
+    # large enough to warrant compression. To turn on compression either pass
+    # <tt>:compress => true</tt> in the initializer or as an option to +fetch+
+    # or +write+. To specify the threshold at which to compress values, set the
+    # <tt>:compress_threshold</tt> option. The default threshold is 32K.
     class Store
 
       cattr_accessor :logger, :instance_writer => true
@@ -180,11 +181,11 @@ def self.instrument
       # Fetches data from the cache, using the given key. If there is data in
       # the cache with the given key, then that data is returned.
       #
-      # If there is no such data in the cache (a cache miss occurred),
-      # then nil will be returned. However, if a block has been passed, then
-      # that block will be run in the event of a cache miss. The return value
-      # of the block will be written to the cache under the given cache key,
-      # and that return value will be returned.
+      # If there is no such data in the cache (a cache miss), then nil will be
+      # returned. However, if a block has been passed, that block will be run
+      # in the event of a cache miss. The return value of the block will be
+      # written to the cache under the given cache key, and that return value
+      # will be returned.
       #
       #   cache.write("today", "Monday")
       #   cache.fetch("today")  # => "Monday"
@@ -205,10 +206,11 @@ def self.instrument
       # in a compressed format.
       #
       #
-      # Setting <tt>:expires_in</tt> will set an expiration time on the cache. All caches
-      # support auto expiring content after a specified number of seconds. This value can
-      # be specified as an option to the construction in which call all entries will be
-      # affected. Or it can be supplied to the +fetch+ or +write+ method for just one entry.
+      # Setting <tt>:expires_in</tt> will set an expiration time on the cache.
+      # All caches support auto-expiring content after a specified number of
+      # seconds. This value can be specified as an option to the constructor
+      # (in which case all entries will be affected), or it can be supplied to
+      # the +fetch+ or +write+ method to effect just one entry.
       #
       #   cache = ActiveSupport::Cache::MemoryStore.new(:expires_in => 5.minutes)
       #   cache.write(key, value, :expires_in => 1.minute)  # Set a lower value for one entry

activesupport/lib/active_support/core_ext/string/output_safety.rb

@@ -137,14 +137,14 @@ def to_yaml(*args)
 
     UNSAFE_STRING_METHODS.each do |unsafe_method|
       class_eval <<-EOT, __FILE__, __LINE__
-        def #{unsafe_method}(*args, &block)
-          to_str.#{unsafe_method}(*args, &block)
-        end
-
-        def #{unsafe_method}!(*args)
-          @dirty = true
-          super
-        end
+        def #{unsafe_method}(*args, &block)       # def gsub(*args, &block)
+          to_str.#{unsafe_method}(*args, &block)  #   to_str.gsub(*args, &block)
+        end                                       # end
+
+        def #{unsafe_method}!(*args)              # def gsub!(*args)
+          @dirty = true                           #   @dirty = true
+          super                                   #   super
+        end                                       # end
       EOT
     end
 

activesupport/lib/active_support/testing/assertions.rb

@@ -68,7 +68,7 @@ def assert_difference(expression, difference = 1, message = nil, &block)
       #
       # A error message can be specified.
       #
-      #   assert_no_difference 'Article.count', "An Article should not be destroyed" do
+      #   assert_no_difference 'Article.count', "An Article should not be created" do
       #     post :create, :article => invalid_attributes
       #   end
       def assert_no_difference(expression, message = nil, &block)

railties/guides/source/action_controller_overview.textile

@@ -802,7 +802,7 @@ class DinnerController
 end
 </ruby>
 
-Just like the filter, you could also passing +:only+ and +:except+ to enforce the secure connection only to specific actions
+Just like the filter, you could also passing +:only+ and +:except+ to enforce the secure connection only to specific actions.
 
 <ruby>
 class DinnerController

railties/guides/source/action_mailer_basics.textile

@@ -276,6 +276,27 @@ Mailer views are located in the +app/views/name_of_mailer_class+ directory. The
 
 To change the default mailer view for your action you do something like:
 
+<ruby>
+class UserMailer < ActionMailer::Base
+  default :from => "notifications@example.com"
+
+  def welcome_email(user)
+    @user = user
+    @url  = "http://example.com/login"
+    mail(:to => user.email,
+         :subject => "Welcome to My Awesome Site",
+         :template_path => 'notifications',
+         :template_name => 'another')
+    end
+  end
+
+end
+</ruby>
+
+In this case it will look for templates at +app/views/notifications+ with name +another+.
+
+If you want more flexibility you can also pass a block and render specific templates or even render inline or text without using a template file:
+
 <ruby>
 class UserMailer < ActionMailer::Base
   default :from => "notifications@example.com"
@@ -286,14 +307,14 @@ class UserMailer < ActionMailer::Base
     mail(:to => user.email,
          :subject => "Welcome to My Awesome Site") do |format|
       format.html { render 'another_template' }
-      format.text { render 'another_template' }
+      format.text { render :text => 'Render text' }
     end
   end
 
 end
 </ruby>
 
-Will render 'another_template.text.erb' and 'another_template.html.erb'. The render command is the same one used inside of Action Controller, so you can use all the same options, such as <tt>:text</tt> etc.
+This will render the template 'another_template.html.erb' for the HTML part and use the rendered text for the text part. The render command is the same one used inside of Action Controller, so you can use all the same options, such as <tt>:text</tt>, <tt>:inline</tt> etc.
 
 h4. Action Mailer Layouts