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

11 files changed, 63 insertions, 27 deletions

diff --git a/actionpack/lib/action_controller/vendor/html-scanner/html/sanitizer.rb b/actionpack/lib/action_controller/vendor/html-scanner/html/sanitizer.rb
index e9b50ff8ce..114b0e73c9 100644
--- a/actionpack/lib/action_controller/vendor/html-scanner/html/sanitizer.rb
+++ b/actionpack/lib/action_controller/vendor/html-scanner/html/sanitizer.rb
@@ -99,7 +99,7 @@ module HTML
     self.allowed_protocols      = Set.new(%w(ed2k ftp http https irc mailto news gopher nntp telnet webcal xmpp callto
       feed svn urn aim rsync tag ssh sftp rtsp afs))
 
-    # Specifies the default Set of acceptable css keywords that #sanitize and #sanitize_css will accept.
+    # Specifies the default Set of acceptable css properties that #sanitize and #sanitize_css will accept.
     self.allowed_css_properties = Set.new(%w(azimuth background-color border-bottom-color border-collapse
       border-color border-left-color border-right-color border-top-color clear color cursor direction display
       elevation float font font-family font-size font-style font-variant font-weight height letter-spacing line-height
diff --git a/actionpack/lib/action_dispatch/http/response.rb b/actionpack/lib/action_dispatch/http/response.rb
index 078229efd2..cc46f9983c 100644
--- a/actionpack/lib/action_dispatch/http/response.rb
+++ b/actionpack/lib/action_dispatch/http/response.rb
@@ -29,7 +29,7 @@ module ActionDispatch # :nodoc:
   #  class DemoControllerTest < ActionDispatch::IntegrationTest
   #    def test_print_root_path_to_console
   #      get('/')
-  #      puts @response.body
+  #      puts response.body
   #    end
   #  end
   class Response
diff --git a/actionpack/lib/action_dispatch/middleware/flash.rb b/actionpack/lib/action_dispatch/middleware/flash.rb
index cff0877030..c92c91df65 100644
--- a/actionpack/lib/action_dispatch/middleware/flash.rb
+++ b/actionpack/lib/action_dispatch/middleware/flash.rb
@@ -17,7 +17,7 @@ module ActionDispatch
   #     def create
   #       # save post
   #       flash[:notice] = "Post successfully created"
-  #       redirect_to posts_path(@post)
+  #       redirect_to @post
   #     end
   #
   #     def show
diff --git a/actionpack/lib/action_dispatch/routing/redirection.rb b/actionpack/lib/action_dispatch/routing/redirection.rb
index 617b24b46a..f281738e6f 100644
--- a/actionpack/lib/action_dispatch/routing/redirection.rb
+++ b/actionpack/lib/action_dispatch/routing/redirection.rb
@@ -67,10 +67,13 @@ module ActionDispatch
       # params, depending of how many arguments your block accepts. A string is required as a
       # return value.
       #
-      #   match 'jokes/:number', :to => redirect do |params, request|
-      #     path = (params[:number].to_i.even? ? "/wheres-the-beef" : "/i-love-lamp")
+      #   match 'jokes/:number', :to => redirect { |params, request|
+      #     path = (params[:number].to_i.even? ? "wheres-the-beef" : "i-love-lamp")
       #     "http://#{request.host_with_port}/#{path}"
-      #   end
+      #   }
+      #
+      # Note that the `do end` syntax for the redirect block wouldn't work, as Ruby would pass
+      # the block to `match` instead of `redirect`. Use `{ ... }` instead.
       #
       # The options version of redirect allows you to supply only the parts of the url which need
       # to change, it also supports interpolation of the path similar to the first example.
diff --git a/activemodel/lib/active_model/errors.rb b/activemodel/lib/active_model/errors.rb
index 016bf87d86..0c628c33c2 100644
--- a/activemodel/lib/active_model/errors.rb
+++ b/activemodel/lib/active_model/errors.rb
@@ -130,12 +130,12 @@ module ActiveModel
     # has more than one error message, yields once for each error message.
     #
     #   p.errors.add(:name, "can't be blank")
-    #   p.errors.each do |attribute, errors_array|
+    #   p.errors.each do |attribute, error|
     #     # Will yield :name and "can't be blank"
     #   end
     #
     #   p.errors.add(:name, "must be specified")
-    #   p.errors.each do |attribute, errors_array|
+    #   p.errors.each do |attribute, error|
     #     # Will yield :name and "can't be blank"
     #     # then yield :name and "must be specified"
     #   end
diff --git a/activemodel/lib/active_model/model.rb b/activemodel/lib/active_model/model.rb
index 6825fdc653..3af95b09b0 100644
--- a/activemodel/lib/active_model/model.rb
+++ b/activemodel/lib/active_model/model.rb
@@ -2,11 +2,11 @@ module ActiveModel
 
   # == Active Model Basic Model
   #
-  # Includes the required interface for an object to interact with +ActionPack+,
-  # using different +ActiveModel+ modules. It includes model name introspections,
+  # Includes the required interface for an object to interact with <tt>ActionPack</tt>,
+  # using different <tt>ActiveModel</tt> modules. It includes model name introspections,
   # conversions, translations and validations. Besides that, it allows you to
   # initialize the object with a hash of attributes, pretty much like
-  # +ActiveRecord+ does.
+  # <tt>ActiveRecord</tt> does.
   #
   # A minimal implementation could be:
   #
@@ -19,8 +19,8 @@ module ActiveModel
   #   person.name # => 'bob'
   #   person.age # => 18
   #
-  # Note that, by default, +ActiveModel::Model+ implements +persisted?+ to
-  # return +false+, which is the most common case. You may want to override it
+  # Note that, by default, <tt>ActiveModel::Model</tt> implements <tt>persisted?</tt> to
+  # return <tt>false</tt>, which is the most common case. You may want to override it
   # in your class to simulate a different scenario:
   #
   #   class Person
@@ -35,14 +35,14 @@ module ActiveModel
   #   person = Person.new(:id => 1, :name => 'bob')
   #   person.persisted? # => true
   #
-  # Also, if for some reason you need to run code on +initialize+, make sure you
+  # Also, if for some reason you need to run code on <tt>initialize</tt>, make sure you
   # call super if you want the attributes hash initialization to happen.
   #
   #   class Person
   #     include ActiveModel::Model
   #     attr_accessor :id, :name, :omg
   #
-  #     def initialize(attributes)
+  #     def initialize(attributes={})
   #       super
   #       @omg ||= true
   #     end
@@ -52,7 +52,7 @@ module ActiveModel
   #   person.omg # => true
   #
   # For more detailed information on other functionalities available, please refer
-  # to the specific modules included in +ActiveModel::Model+ (see below).
+  # to the specific modules included in <tt>ActiveModel::Model</tt> (see below).
   module Model
     def self.included(base)
       base.class_eval do
diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb
index c39c85e1af..dbafd0bd1a 100644
--- a/activemodel/lib/active_model/validations/callbacks.rb
+++ b/activemodel/lib/active_model/validations/callbacks.rb
@@ -8,7 +8,8 @@ module ActiveModel
       # Provides an interface for any class to have <tt>before_validation</tt> and
       # <tt>after_validation</tt> callbacks.
       #
-      # First, extend ActiveModel::Callbacks from the class you are creating:
+      # First, include ActiveModel::Validations::Callbacks from the class you are
+      # creating:
       #
       #   class MyModel
       #     include ActiveModel::Validations::Callbacks
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index 10b3657ced..30a4f9aa35 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -376,7 +376,7 @@ module ActiveRecord
       # Note: SQLite doesn't support index length
       #
       # ====== Creating an index with a sort order (desc or asc, asc is the default)
-      #  add_index(:accounts, [:branch_id, :party_id, :surname], :order => {:branch_id => :desc, :part_id => :asc})
+      #  add_index(:accounts, [:branch_id, :party_id, :surname], :order => {:branch_id => :desc, :party_id => :asc})
       # generates
       #  CREATE INDEX by_branch_desc_party ON accounts(branch_id DESC, party_id ASC, surname)
       #
diff --git a/activesupport/lib/active_support/notifications.rb b/activesupport/lib/active_support/notifications.rb
index 8cf7bdafda..6735c561d3 100644
--- a/activesupport/lib/active_support/notifications.rb
+++ b/activesupport/lib/active_support/notifications.rb
@@ -4,7 +4,7 @@ require 'active_support/notifications/fanout'
 module ActiveSupport
   # = Notifications
   #
-  # +ActiveSupport::Notifications+ provides an instrumentation API for Ruby.
+  # <tt>ActiveSupport::Notifications</tt> provides an instrumentation API for Ruby.
   #
   # == Instrumenters
   #
@@ -44,26 +44,53 @@ module ActiveSupport
   #   event.duration  # => 10 (in milliseconds)
   #   event.payload   # => { :extra => :information }
   #
-  # The block in the +subscribe+ call gets the name of the event, start
+  # The block in the <tt>subscribe</tt> call gets the name of the event, start
   # timestamp, end timestamp, a string with a unique identifier for that event
   # (something like "535801666f04d0298cd6"), and a hash with the payload, in
   # that order.
   #
   # If an exception happens during that particular instrumentation the payload will
-  # have a key +:exception+ with an array of two elements as value: a string with
+  # have a key <tt>:exception</tt> with an array of two elements as value: a string with
   # the name of the exception class, and the exception message.
   #
-  # As the previous example depicts, the class +ActiveSupport::Notifications::Event+
+  # As the previous example depicts, the class <tt>ActiveSupport::Notifications::Event</tt>
   # is able to take the arguments as they come and provide an object-oriented
   # interface to that data.
   #
+  # It is also possible to pass an object as the second parameter passed to the
+  # <tt>subscribe</tt> method instead of a block:
+  #
+  #   module ActionController
+  #     class PageRequest
+  #       def call(name, started, finished, unique_id, payload)
+  #         Rails.logger.debug ["notification:", name, started, finished, unique_id, payload].join(" ")
+  #       end
+  #     end
+  #   end
+  #
+  #   ActiveSupport::Notifications.subscribe('process_action.action_controller', ActionController::PageRequest.new)
+  #
+  # resulting in the following output within the logs including a hash with the payload:
+  #
+  #   notification: process_action.action_controller 2012-04-13 01:08:35 +0300 2012-04-13 01:08:35 +0300 af358ed7fab884532ec7 {
+  #      :controller=>"Devise::SessionsController",
+  #      :action=>"new",
+  #      :params=>{"action"=>"new", "controller"=>"devise/sessions"},
+  #      :format=>:html,
+  #      :method=>"GET",
+  #      :path=>"/login/sign_in",
+  #      :status=>200,
+  #      :view_runtime=>279.3080806732178,
+  #      :db_runtime=>40.053
+  #    }
+  #
   # You can also subscribe to all events whose name matches a certain regexp:
   #
   #   ActiveSupport::Notifications.subscribe(/render/) do |*args|
   #     ...
   #   end
   #
-  # and even pass no argument to +subscribe+, in which case you are subscribing
+  # and even pass no argument to <tt>subscribe</tt>, in which case you are subscribing
   # to all events.
   #
   # == Temporary Subscriptions
diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile
index de55401c1f..58eae2ee0f 100644
--- a/guides/source/active_record_querying.textile
+++ b/guides/source/active_record_querying.textile
@@ -539,7 +539,9 @@ And this will give you a single +Order+ object for each date where there are ord
 The SQL that would be executed would be something like this:
 
 <sql>
-SELECT date(created_at) as ordered_date, sum(price) as total_price FROM orders GROUP BY date(created_at)
+SELECT date(created_at) as ordered_date, sum(price) as total_price 
+FROM orders 
+GROUP BY date(created_at)
 </sql>
 
 h3. Having
@@ -555,7 +557,10 @@ Order.select("date(created_at) as ordered_date, sum(price) as total_price").grou
 The SQL that would be executed would be something like this:
 
 <sql>
-SELECT date(created_at) as ordered_date, sum(price) as total_price FROM orders GROUP BY date(created_at) HAVING sum(price) > 100
+SELECT date(created_at) as ordered_date, sum(price) as total_price 
+FROM orders 
+GROUP BY date(created_at) 
+HAVING sum(price) > 100
 </sql>
 
 This will return single order objects for each day, but only those that are ordered more than $100 in a day.
@@ -829,7 +834,7 @@ SELECT categories.* FROM categories
   INNER JOIN posts ON posts.category_id = categories.id
 </sql>
 
-Or, in English: "return a Category object for all categories with posts". Note that you will see duplicate categories if more than one post has the same category. If you want unique categories, you can use Category.joins(:post).select("distinct(categories.id)").
+Or, in English: "return a Category object for all categories with posts". Note that you will see duplicate categories if more than one post has the same category. If you want unique categories, you can use Category.joins(:posts).select("distinct(categories.id)").
 
 h5. Joining Multiple Associations
 
diff --git a/guides/source/migrations.textile b/guides/source/migrations.textile
index aa75e9ab4a..1eeb27f3c1 100644
--- a/guides/source/migrations.textile
+++ b/guides/source/migrations.textile
@@ -779,7 +779,7 @@ Both migrations work for Alice.
 
 Bob comes back from vacation and:
 
-# Updates the source - which contains both migrations and the latests version of
+# Updates the source - which contains both migrations and the latest version of
 the Product model.
 # Runs outstanding migrations with +rake db:migrate+, which
 includes the one that updates the +Product+ model.