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

actionpack/lib/action_controller/base.rb

@@ -171,6 +171,16 @@ module ActionController
   class Base < Metal
     abstract!
 
+    # Shortcut helper that returns all the ActionController modules except the ones passed in the argument:
+    #
+    #   class MetalController
+    #     ActionController::Base.without_modules(:ParamsWrapper, :Streaming).each do |module|
+    #       include module
+    #     end
+    #   end
+    #
+    # This gives better control over what you want to exclude and makes it easier
+    # to create a bare controller class, instead of listing the modules required manually.
     def self.without_modules(*modules)
       modules = modules.map do |m|
         m.is_a?(Symbol) ? ActionController.const_get(m) : m

activemodel/lib/active_model/mass_assignment_security.rb

@@ -85,15 +85,15 @@ module ClassMethods
       #     end
       #   end
       #
-      # When using the :default role :
+      # When using the :default role:
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5 }, :as => :default)
       #   customer.name          # => "David"
       #   customer.email # => "a@b.com"
       #   customer.logins_count    # => nil
       #
-      # And using the :admin role :
+      # And using the :admin role:
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5}, :as => :admin)
@@ -107,8 +107,9 @@ module ClassMethods
       # To start from an all-closed default and enable attributes as needed,
       # have a look at +attr_accessible+.
       #
-      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of +attr_protected+
-      # to sanitize attributes won't provide sufficient protection.
+      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of
+      # +attr_protected+ to sanitize attributes provides basically the same
+      # functionality, but it makes a bit tricky to deal with nested attributes.
       def attr_protected(*args)
         options = args.extract_options!
         role = options[:as] || :default
@@ -152,7 +153,7 @@ def attr_protected(*args)
       #     end
       #   end
       #
-      # When using the :default role :
+      # When using the :default role:
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :default)
@@ -162,15 +163,16 @@ def attr_protected(*args)
       #   customer.credit_rating = "Average"
       #   customer.credit_rating # => "Average"
       #
-      # And using the :admin role :
+      # And using the :admin role:
       #
       #   customer = Customer.new
       #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :admin)
       #   customer.name          # => "David"
       #   customer.credit_rating # => "Excellent"
       #
-      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of +attr_accessible+
-      # to sanitize attributes won't provide sufficient protection.
+      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of
+      # +attr_accessible+ to sanitize attributes provides basically the same
+      # functionality, but it makes a bit tricky to deal with nested attributes.
       def attr_accessible(*args)
         options = args.extract_options!
         role = options[:as] || :default

activerecord/lib/active_record/associations.rb

@@ -1512,8 +1512,8 @@ def belongs_to(name, options = {})
       # * <tt>Developer#projects.size</tt>
       # * <tt>Developer#projects.find(id)</tt>
       # * <tt>Developer#projects.exists?(...)</tt>
-      # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("project_id" => id)</tt>)
-      # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("project_id" => id); c.save; c</tt>)
+      # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("developer_id" => id)</tt>)
+      # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("developer_id" => id); c.save; c</tt>)
       # The declaration may include an options hash to specialize the behavior of the association.
       #
       # === Options

railties/guides/source/active_record_querying.textile

@@ -94,7 +94,7 @@ client = Client.find(10)
 The SQL equivalent of the above is:
 
 <sql>
-SELECT * FROM clients WHERE (clients.id = 10)
+SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1
 </sql>
 
 <tt>Model.find(primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception if no matching record is found.

railties/guides/source/active_support_instrumentation.textile

@@ -0,0 +1,39 @@
+h2. Active Support Instrumentation
+
+Active Support is a part of core Rails that provides Ruby language extensions, utilities and other things. One of the things it includes is an instrumentation API that can be used inside an application to measure certain actions that occur within Ruby code, such as that inside a Rails application or the framework itself. It is not limited to Rails, however. It can be used independently in other Ruby scripts if it is so desired.
+
+In this guide, you will learn how to use the instrumentation API inside of ActiveSupport to measure events inside of Rails and other Ruby code. We cover:
+
+* What instrumentation can provide
+* The hooks inside the Rails framework for instrumentation
+* Adding a subscriber to a hook
+* Building a custom instrumentation implementation
+
+endprologue.
+
+h3. Introduction to instrumentation
+
+The instrumentation API provided by ActiveSupport allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
+
+For example, there is a hook provided within Active Record that is called every time Active Record uses a SQL query on a database. This hook could be *subscribed* to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
+
+You are even able to create your own events inside your application which you can later subscribe to.
+
+h3. Rails framework hooks
+
+h4. Action Mailer
+
+h4. Action Controller
+
+h4. Action View
+
+h4. Active Record
+
+h4. Active Resource
+
+h4. Active Support
+
+h3. Subscribing to an event
+
+h3. Creating custom events
+

railties/guides/source/ajax_on_rails.textile

@@ -134,7 +134,7 @@ If the server returns 200, the output of the above example is equivalent to our
 ** *position* By default (i.e. when not specifying this option, like in the examples before) the response is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the +position+ parameter, with four possibilities:
 *** +:before+ Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element.
 *** +:after+ Similar behavior to +:before+, but in this case the response is inserted after the target element.
-*** +:top+ Inserts the text into the target element, before it's original content. If the target element was empty, this is equivalent with not specifying +:position+ at all.
+*** +:top+ Inserts the text into the target element, before its original content. If the target element was empty, this is equivalent with not specifying +:position+ at all.
 *** +:bottom+ The counterpart of +:top+: the response is inserted after the target element's original content.
 
 A typical example of using +:bottom+ is inserting a new <li> element into an existing list:
@@ -174,7 +174,7 @@ link_to_remote "Update record",
 
 This generates a remote link which adds 2 parameters to the standard URL generated by Rails, taken from the page (contained in the elements matched by the 'status' and 'completed' DOM id).
 
-** *Callbacks* Since an AJAX call is typically asynchronous, as it's name suggests (this is not a rule, and you can fire a synchronous request - see the last option, +:type+) your only way of communicating with a request once it is fired is via specifying callbacks. There are six options at your disposal (in fact 508, counting all possible response types, but these six are the most frequent and therefore specified by a constant):
+** *Callbacks* Since an AJAX call is typically asynchronous, as its name suggests (this is not a rule, and you can fire a synchronous request - see the last option, +:type+) your only way of communicating with a request once it is fired is via specifying callbacks. There are six options at your disposal (in fact 508, counting all possible response types, but these six are the most frequent and therefore specified by a constant):
 *** +:loading:+ => +code+ The request is in the process of receiving the data, but the transfer is not completed yet.
 *** +:loaded:+ => +code+ The transfer is completed, but the data is not processed and returned yet
 *** +:interactive:+ => +code+ One step after +:loaded+: The data is fully received and being processed
@@ -203,16 +203,16 @@ link_to_remote "Add new item",
 ** *:type* If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the +:type+ option with the value of +:synchronous+.
 * Finally, using the +html_options+ parameter you can add HTML attributes to the generated tag. It works like the same parameter of the +link_to+ helper. There are interesting side effects for the +href+ and +onclick+ parameters though:
 ** If you specify the +href+ parameter, the AJAX link will degrade gracefully, i.e. the link will point to the URL even if JavaScript is disabled in the client browser
-** +link_to_remote+ gains it's AJAX behavior by specifying the remote call in the onclick handler of the link. If you supply +html_options[:onclick]+ you override the default behavior, so use this with care!
+** +link_to_remote+ gains its AJAX behavior by specifying the remote call in the onclick handler of the link. If you supply +html_options[:onclick]+ you override the default behavior, so use this with care!
 
 We are finished with +link_to_remote+. I know this is quite a lot to digest for one helper function, but remember, these options are common for all the rest of the Rails view helpers, so we will take a look at the differences / additional parameters in the next sections.
 
 h4. AJAX Forms
 
 There are three different ways of adding AJAX forms to your view using Rails Prototype helpers. They are slightly different, but striving for the same goal: instead of submitting the form using the standard HTTP request/response cycle, it is submitted asynchronously, thus not reloading the page. These methods are the following:
 
-* +remote_form_for+ (and it's alias +form_remote_for+) is tied to Rails most tightly of the three since it takes a resource, model or array of resources (in case of a nested resource) as a parameter.
-* +form_remote_tag+ AJAXifies the form by serializing and sending it's data in the background
+* +remote_form_for+ (and its alias +form_remote_for+) is tied to Rails most tightly of the three since it takes a resource, model or array of resources (in case of a nested resource) as a parameter.
+* +form_remote_tag+ AJAXifies the form by serializing and sending its data in the background
 * +submit_to_remote+ and +button_to_remote+ is more rarely used than the previous two. Rather than creating an AJAX form, you add a button/input
 
 Let's see them in action one by one!

railties/guides/source/asset_pipeline.textile

@@ -128,7 +128,7 @@ For example, these files:
 <plain>
 app/assets/javascripts/home.js
 lib/assets/javascripts/moovinator.js
-vendor/assets/javascript/slider.js
+vendor/assets/javascripts/slider.js
 </plain>
 
 would be referenced in a manifest like this:

railties/guides/source/configuring.textile

@@ -493,7 +493,7 @@ Rails has 5 initialization events which can be hooked into (listed in the order
 
 * +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run.
 
-To define an event for these hooks, use the block syntax within a +Rails::Aplication+, +Rails::Railtie+ or +Rails::Engine+ subclass:
+To define an event for these hooks, use the block syntax within a +Rails::Application+, +Rails::Railtie+ or +Rails::Engine+ subclass:
 
 <ruby>
 module YourApp

railties/guides/source/routing.textile

@@ -234,14 +234,14 @@ end
 
 In addition to the routes for magazines, this declaration will also route ads to an +AdsController+. The ad URLs require a magazine:
 
-|_.HTTP Verb |_.Path                      |_.action |_.used for                                                                 |
-|GET         |/magazines/:id/ads          |index    |display a list of all ads for a specific magazine                          |
-|GET         |/magazines/:id/ads/new      |new      |return an HTML form for creating a new ad belonging to a specific magazine |
-|POST        |/magazines/:id/ads          |create   |create a new ad belonging to a specific magazine                           |
-|GET         |/magazines/:id/ads/:id      |show     |display a specific ad belonging to a specific magazine                     |
-|GET         |/magazines/:id/ads/:id/edit |edit     |return an HTML form for editing an ad belonging to a specific magazine     |
-|PATCH/PUT   |/magazines/:id/ads/:id      |update   |update a specific ad belonging to a specific magazine                      |
-|DELETE      |/magazines/:id/ads/:id      |destroy  |delete a specific ad belonging to a specific magazine                      |
+|_.HTTP Verb |_.Path                               |_.action |_.used for                                                                 |
+|GET         |/magazines/:magazine_id/ads          |index    |display a list of all ads for a specific magazine                          |
+|GET         |/magazines/:magazine_id/ads/new      |new      |return an HTML form for creating a new ad belonging to a specific magazine |
+|POST        |/magazines/:magazine_id/ads          |create   |create a new ad belonging to a specific magazine                           |
+|GET         |/magazines/:magazine_id/ads/:id      |show     |display a specific ad belonging to a specific magazine                     |
+|GET         |/magazines/:magazine_id/ads/:id/edit |edit     |return an HTML form for editing an ad belonging to a specific magazine     |
+|PATCH/PUT   |/magazines/:magazine_id/ads/:id      |update   |update a specific ad belonging to a specific magazine                      |
+|DELETE      |/magazines/:magazine_id/ads/:id      |destroy  |delete a specific ad belonging to a specific magazine                      |
 
 This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+. These helpers take an instance of Magazine as the first parameter (+magazine_ads_url(@magazine)+).
 
@@ -389,7 +389,7 @@ match ':controller/:action/:id/:user_id'
 
 An incoming path of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+.
 
-NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g:
+NOTE: You can't use +:namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g:
 
 <ruby>
 match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/

railties/guides/source/upgrading_ruby_on_rails.textile

@@ -38,14 +38,14 @@ h3. Upgrading from Rails 3.1 to Rails 3.2
 
 If your application is currently on any version of Rails older than 3.1.x, you should upgrade to Rails 3.1 before attempting an update to Rails 3.2.
 
-The following changes are meant for upgrading your application to Rails 3.2.1, the latest 3.2.x version of Rails.
+The following changes are meant for upgrading your application to Rails 3.2.2, the latest 3.2.x version of Rails.
 
 h4(#gemfile3_2). Gemfile
 
 Make the following changes to your +Gemfile+.
 
 <ruby>
-gem 'rails', '= 3.2.1'
+gem 'rails', '= 3.2.2'
 
 group :assets do
   gem 'sass-rails',   '~> 3.2.3'

railties/lib/rails/engine.rb

@@ -245,7 +245,7 @@ module Rails
   #
   # Additionally, an isolated engine will set its name according to namespace, so
   # MyEngine::Engine.engine_name will be "my_engine". It will also set MyEngine.table_name_prefix
-  # to "my_engine_", changing the MyEngine::Article model to use the my_engine_article table.
+  # to "my_engine_", changing the MyEngine::Article model to use the my_engine_articles table.
   #
   # == Using Engine's routes outside Engine
   #