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

11 files changed, 37 insertions, 24 deletions

diff --git a/README.rdoc b/README.rdoc
index dc8805245b..78640b39aa 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -76,4 +76,3 @@ to proceed. {Join us}[http://contributors.rubyonrails.org]!
 Ruby on Rails is released under the MIT license:
 
 * http://www.opensource.org/licenses/MIT
-
diff --git a/actionpack/lib/action_controller/caching/actions.rb b/actionpack/lib/action_controller/caching/actions.rb
index e76a79f710..bd3b0b5df3 100644
--- a/actionpack/lib/action_controller/caching/actions.rb
+++ b/actionpack/lib/action_controller/caching/actions.rb
@@ -47,7 +47,8 @@ module ActionController #:nodoc:
     # And you can also use <tt>:if</tt> (or <tt>:unless</tt>) to pass a
     # proc that specifies when the action should be cached.
     #
-    # Finally, if you are using memcached, you can also pass <tt>:expires_in</tt>.
+    # As of Rails 3.0, you can also pass <tt>:expires_in</tt> with a time 
+    # interval (in seconds) to schedule expiration of the cached item.
     #
     # The following example depicts some of the points made above:
     #
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb
index 2f6b9d266d..107fe80d1f 100644
--- a/actionpack/lib/action_dispatch/routing.rb
+++ b/actionpack/lib/action_dispatch/routing.rb
@@ -190,7 +190,7 @@ module ActionDispatch
   # Examples:
   #
   #   match 'post/:id' => 'posts#show', :via => :get
-  #   match 'post/:id' => "posts#create_comment', :via => :post
+  #   match 'post/:id' => 'posts#create_comment', :via => :post
   #
   # Now, if you POST to <tt>/posts/:id</tt>, it will route to the <tt>create_comment</tt> action. A GET on the same
   # URL will route to the <tt>show</tt> action.
@@ -203,7 +203,7 @@ module ActionDispatch
   # Examples:
   #
   #   get 'post/:id' => 'posts#show'
-  #   post 'post/:id' => "posts#create_comment'
+  #   post 'post/:id' => 'posts#create_comment'
   #
   # This syntax is less verbose and the intention is more apparent to someone else reading your code,
   # however if your route needs to respond to more than one HTTP method (or all methods) then using the
diff --git a/activerecord/lib/active_record/locking/optimistic.rb b/activerecord/lib/active_record/locking/optimistic.rb
index e643c0d437..4d73cdd37a 100644
--- a/activerecord/lib/active_record/locking/optimistic.rb
+++ b/activerecord/lib/active_record/locking/optimistic.rb
@@ -40,11 +40,13 @@ module ActiveRecord
     # This locking mechanism will function inside a single Ruby process. To make it work across all
     # web requests, the recommended approach is to add +lock_version+ as a hidden field to your form.
     #
-    # You must ensure that your database schema defaults the +lock_version+ column to 0.
-    #
     # This behavior can be turned off by setting <tt>ActiveRecord::Base.lock_optimistically = false</tt>.
-    # To override the name of the +lock_version+ column, invoke the <tt>set_locking_column</tt> method.
-    # This method uses the same syntax as <tt>set_table_name</tt>
+    # To override the name of the +lock_version+ column, set the <tt>locking_column</tt> class attribute:
+    #
+    #   class Person < ActiveRecord::Base
+    #     self.locking_column = :lock_person
+    #   end
+    #
     module Optimistic
       extend ActiveSupport::Concern
 
diff --git a/activesupport/lib/active_support/message_encryptor.rb b/activesupport/lib/active_support/message_encryptor.rb
index 6ec5a04933..ada2e79ccb 100644
--- a/activesupport/lib/active_support/message_encryptor.rb
+++ b/activesupport/lib/active_support/message_encryptor.rb
@@ -9,6 +9,11 @@ module ActiveSupport
   #
   # This can be used in situations similar to the <tt>MessageVerifier</tt>, but where you don't
   # want users to be able to determine the value of the payload.
+  #
+  #   key = OpenSSL::Digest::SHA256.new('password').digest        # => "\x89\xE0\x156\xAC..." 
+  #   crypt = ActiveSupport::MessageEncryptor.new(key)            # => #<ActiveSupport::MessageEncryptor ...> 
+  #   encrypted_data = crypt.encrypt_and_sign('my secret data')   # => "NlFBTTMwOUV5UlA1QlNEN2xkY2d6eThYWWh..." 
+  #   crypt.decrypt_and_verify(encrypted_data)                    # => "my secret data" 
   class MessageEncryptor
     module NullSerializer #:nodoc:
       def self.load(value)
@@ -23,6 +28,15 @@ module ActiveSupport
     class InvalidMessage < StandardError; end
     OpenSSLCipherError = OpenSSL::Cipher.const_defined?(:CipherError) ? OpenSSL::Cipher::CipherError : OpenSSL::CipherError
 
+    # Initialize a new MessageEncryptor.
+    # +secret+ must be at least as long as the cipher key size. For the default 'aes-256-cbc' cipher,
+    # this is 256 bits. If you are using a user-entered secret, you can generate a suitable key with
+    # <tt>OpenSSL::Digest::SHA256.new(user_secret).digest</tt> or similar.
+    #
+    # Options:
+    # * <tt>:cipher</tt>      - Cipher to use. Can be any cipher returned by <tt>OpenSSL::Cipher.ciphers</tt>. Default is 'aes-256-cbc'
+    # * <tt>:serializer</tt>  - Object serializer to use. Default is +Marshal+.
+    # 
     def initialize(secret, options = {})
       @secret = secret
       @cipher = options[:cipher] || 'aes-256-cbc'
diff --git a/install.rb b/install.rb
index 05bba27a14..abc02249c2 100644
--- a/install.rb
+++ b/install.rb
@@ -8,4 +8,4 @@ end
 puts "Installing Rails..."
 `gem build rails.gemspec`
 `gem install rails-#{version}.gem --no-ri --no-rdoc `
-`rm rails-#{version}.gem`
\ No newline at end of file
+`rm rails-#{version}.gem`
diff --git a/load_paths.rb b/load_paths.rb
index 17f5ce180d..6b224d4ad5 100644
--- a/load_paths.rb
+++ b/load_paths.rb
@@ -1,4 +1,4 @@
 # bust gem prelude
 require 'rubygems' unless defined? Gem
 require 'bundler'
-Bundler.setup
\ No newline at end of file
+Bundler.setup
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 8517f6fb19..3b4f2befda 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -404,6 +404,8 @@ Or ordering by multiple fields:
 
 <ruby>
 Client.order("orders_count ASC, created_at DESC")
+# OR
+Client.order("orders_count ASC", "created_at DESC")
 </ruby>
 
 h3. Selecting Specific Fields
@@ -608,7 +610,7 @@ This method accepts *no* arguments.
 
 h3. Readonly Objects
 
-Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
+Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
 
 <ruby>
 client = Client.readonly.first
@@ -648,15 +650,13 @@ c2.save # Raises an ActiveRecord::StaleObjectError
 
 You're then responsible for dealing with the conflict by rescuing the exception and either rolling back, merging, or otherwise apply the business logic needed to resolve the conflict.
 
-NOTE: You must ensure that your database schema defaults the +lock_version+ column to +0+.
-
 This behavior can be turned off by setting <tt>ActiveRecord::Base.lock_optimistically = false</tt>.
 
-To override the name of the +lock_version+ column, +ActiveRecord::Base+ provides a class method called +set_locking_column+:
+To override the name of the +lock_version+ column, +ActiveRecord::Base+ provides a class attribute called +locking_column+:
 
 <ruby>
 class Client < ActiveRecord::Base
-  set_locking_column :lock_client_column
+  self.locking_column = :lock_client_column
 end
 </ruby>
 
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile
index 451653655f..a55ed38d1b 100644
--- a/railties/guides/source/association_basics.textile
+++ b/railties/guides/source/association_basics.textile
@@ -1120,7 +1120,7 @@ h6(#has_many-collection-find). <tt><em>collection</em>.find(...)</tt>
 The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+.
 
 <ruby>
-@open_orders = @customer.orders.where(:open => 1)
+@open_orders = @customer.orders.find(1)
 </ruby>
 
 h6(#has_many-collection-where). <tt><em>collection</em>.where(...)</tt>
@@ -1242,7 +1242,7 @@ h6(#has_many-counter_sql). +:counter_sql+
 
 Normally Rails automatically generates the proper SQL to count the association members. With the +:counter_sql+ option, you can specify a complete SQL statement to count them yourself.
 
-NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL will be generated by substituting +SELECT COUNT(*) FROM+ for the +SELECT ... FROM+ clause of your +:finder_sql+ statement.
+NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL will be generated by substituting the +SELECT ... FROM+ clause of your +:finder_sql+ statement by +SELECT COUNT(*) FROM+.
 
 h6(#has_many-dependent). +:dependent+
 
@@ -1545,12 +1545,9 @@ h6(#has_and_belongs_to_many-collection-find). <tt><em>collection</em>.find(...)<
 The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+. It also adds the additional condition that the object must be in the collection.
 
 <ruby>
-@new_assemblies = @part.assemblies.all(
-  :conditions => ["created_at > ?", 2.days.ago])
+@assembly = @part.assemblies.find(1)
 </ruby>
 
-NOTE: Beginning with Rails 3, supplying options to the +ActiveRecord::Base.find+ method is discouraged. Use <tt><em>collection</em>.where</tt> instead when you need to pass conditions.
-
 h6(#has_and_belongs_to_many-collection-where). <tt><em>collection</em>.where(...)</tt>
 
 The <tt><em>collection</em>.where</tt> method finds objects within the collection based on the conditions supplied but the objects are loaded lazily meaning that the database is queried only when the object(s) are accessed. It also adds the additional condition that the object must be in the collection.
@@ -1669,7 +1666,7 @@ h6(#has_and_belongs_to_many-counter_sql). +:counter_sql+
 
 Normally Rails automatically generates the proper SQL to count the association members. With the +:counter_sql+ option, you can specify a complete SQL statement to count them yourself.
 
-NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL will be generated by substituting +SELECT COUNT(*) FROM+ for the +SELECT ... FROM+ clause of your +:finder_sql+ statement.
+NOTE: If you specify +:finder_sql+ but not +:counter_sql+, then the counter SQL will be generated by substituting the +SELECT ... FROM+ clause of your +:finder_sql+ statement by +SELECT COUNT(*) FROM+.
 
 h6(#has_and_belongs_to_many-delete_sql). +:delete_sql+
 
diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile
index 1681629620..9758b639cf 100644
--- a/railties/guides/source/form_helpers.textile
+++ b/railties/guides/source/form_helpers.textile
@@ -754,7 +754,7 @@ produces exactly the same output as the previous example.
 
 h3. Forms to external resources
 
-If you need to post some data to an external resource it is still great to build your from using rails form helpers. But sometimes you need to set an +authenticity_token+ for this resource. You can do it by passing an +:authenticity_token => 'your_external_token'+ parameter to the +form_tag+ options:
+If you need to post some data to an external resource it is still great to build your form using rails form helpers. But sometimes you need to set an +authenticity_token+ for this resource. You can do it by passing an +:authenticity_token => 'your_external_token'+ parameter to the +form_tag+ options:
 
 <erb>
 <%= form_tag 'http://farfar.away/form', :authenticity_token => 'external_token') do %>
diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile
index c2ef7bf9b5..b1a09c0c05 100644
--- a/railties/guides/source/security.textile
+++ b/railties/guides/source/security.textile
@@ -385,7 +385,7 @@ params[:user] # => {:name => “ow3ned”, :admin => true}
 
 So if you create a new user using mass-assignment, it may be too easy to become an administrator.
 
-Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the <tt>attributes=</tt> method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3+. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example:
+Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the <tt>attributes=</tt> method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3<plus>. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example:
 
 <ruby>
   class Person < ActiveRecord::Base