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

6 files changed, 59 insertions, 36 deletions

diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 3f2fd12db7..7014d8114f 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -11,14 +11,14 @@ module ActiveModel
   #
   # The requirements for implementing ActiveModel::Dirty are:
   #
-  # * <tt>include ActiveModel::Dirty</tt> in your object
+  # * <tt>include ActiveModel::Dirty</tt> in your object.
   # * Call <tt>define_attribute_methods</tt> passing each method you want to
-  #   track
+  #   track.
   # * Call <tt>attr_name_will_change!</tt> before each change to the tracked
-  #   attribute
+  #   attribute.
   #
   # If you wish to also track previous changes on save or update, you need to
-  # add
+  # add:
   #
   #   @previously_changed = changes
   #
@@ -27,7 +27,6 @@ module ActiveModel
   # A minimal implementation could be:
   #
   #   class Person
-  #
   #     include ActiveModel::Dirty
   #
   #     define_attribute_methods :name
@@ -45,47 +44,49 @@ module ActiveModel
   #       @previously_changed = changes
   #       @changed_attributes.clear
   #     end
-  #
   #   end
   #
-  # == Examples:
-  #
   # A newly instantiated object is unchanged:
+  #
   #   person = Person.find_by_name('Uncle Bob')
   #   person.changed?       # => false
   #
   # Change the name:
+  #
   #   person.name = 'Bob'
   #   person.changed?       # => true
   #   person.name_changed?  # => true
-  #   person.name_was       # => 'Uncle Bob'
-  #   person.name_change    # => ['Uncle Bob', 'Bob']
+  #   person.name_was       # => "Uncle Bob"
+  #   person.name_change    # => ["Uncle Bob", "Bob"]
   #   person.name = 'Bill'
-  #   person.name_change    # => ['Uncle Bob', 'Bill']
+  #   person.name_change    # => ["Uncle Bob", "Bill"]
   #
   # Save the changes:
+  #
   #   person.save
   #   person.changed?       # => false
   #   person.name_changed?  # => false
   #
   # Assigning the same value leaves the attribute unchanged:
+  #
   #   person.name = 'Bill'
   #   person.name_changed?  # => false
   #   person.name_change    # => nil
   #
   # Which attributes have changed?
+  #
   #   person.name = 'Bob'
-  #   person.changed        # => ['name']
-  #   person.changes        # => { 'name' => ['Bill', 'Bob'] }
+  #   person.changed        # => ["name"]
+  #   person.changes        # => {"name" => ["Bill", "Bob"]}
   #
   # If an attribute is modified in-place then make use of <tt>[attribute_name]_will_change!</tt>
   # to mark that the attribute is changing. Otherwise ActiveModel can't track changes to
   # in-place attributes.
   #
   #   person.name_will_change!
-  #   person.name_change    # => ['Bill', 'Bill']
+  #   person.name_change    # => ["Bill", "Bill"]
   #   person.name << 'y'
-  #   person.name_change    # => ['Bill', 'Billy']
+  #   person.name_change    # => ["Bill", "Billy"]
   module Dirty
     extend ActiveSupport::Concern
     include ActiveModel::AttributeMethods
@@ -95,7 +96,8 @@ module ActiveModel
       attribute_method_affix :prefix => 'reset_', :suffix => '!'
     end
 
-    # Returns true if any attribute have unsaved changes, false otherwise.
+    # Returns +true+ if any attribute have unsaved changes, +false+ otherwise.
+    #
     #   person.changed? # => false
     #   person.name = 'bob'
     #   person.changed? # => true
@@ -103,32 +105,41 @@ module ActiveModel
       changed_attributes.present?
     end
 
-    # List of attributes with unsaved changes.
+    # Returns an array with the name of the attributes with unsaved changes.
+    #
     #   person.changed # => []
     #   person.name = 'bob'
-    #   person.changed # => ['name']
+    #   person.changed # => ["name"]
     def changed
       changed_attributes.keys
     end
 
-    # Map of changed attrs => [original value, new value].
+    # Returns a hash of changed attributes indicating their original
+    # and new values like <tt>attr => [original value, new value]</tt>. 
+    #
     #   person.changes # => {}
     #   person.name = 'bob'
-    #   person.changes # => { 'name' => ['bill', 'bob'] }
+    #   person.changes # => { "name" => ["bill", "bob"] }
     def changes
       HashWithIndifferentAccess[changed.map { |attr| [attr, attribute_change(attr)] }]
     end
 
-    # Map of attributes that were changed when the model was saved.
-    #   person.name # => 'bob'
+    # Returns a hash of attributes that were changed before the model was saved.
+    #
+    #   person.name # => "bob"
     #   person.name = 'robert'
     #   person.save
-    #   person.previous_changes # => {'name' => ['bob, 'robert']}
+    #   person.previous_changes # => {"name" => ["bob", "robert"]}
     def previous_changes
       @previously_changed
     end
 
-    # Map of change <tt>attr => original value</tt>.
+    # Returns a hash of the attributes with unsaved changes indicating their original
+    # values like <tt>attr => original value</tt>.
+    #
+    #   person.name # => "bob"
+    #   person.name = 'robert'
+    #   person.changed_attributes # => {"name" => "bob"}
     def changed_attributes
       @changed_attributes ||= {}
     end
diff --git a/activesupport/lib/active_support/json/encoding.rb b/activesupport/lib/active_support/json/encoding.rb
index 6ed253e141..c319e94bc6 100644
--- a/activesupport/lib/active_support/json/encoding.rb
+++ b/activesupport/lib/active_support/json/encoding.rb
@@ -191,7 +191,7 @@ end
 
 class Float
   # Encoding Infinity or NaN to JSON should return "null". The default returns
-  # "Infinity" or "NaN" breaks parsing the JSON. E.g. JSON.parse('[NaN]').
+  # "Infinity" or "NaN" which breaks parsing the JSON. E.g. JSON.parse('[NaN]').
   def as_json(options = nil) finite? ? self : nil end #:nodoc:
 end
 
diff --git a/guides/code/getting_started/app/controllers/home_controller.rb b/guides/code/getting_started/app/controllers/welcome_controller.rb
index 309b70441e..f9b859b9c9 100644
--- a/guides/code/getting_started/app/controllers/home_controller.rb
+++ b/guides/code/getting_started/app/controllers/welcome_controller.rb
@@ -1,5 +1,4 @@
 class WelcomeController < ApplicationController
   def index
   end
-
 end
diff --git a/guides/code/getting_started/test/functional/home_controller_test.rb b/guides/code/getting_started/test/functional/welcome_controller_test.rb
index dff8e9d2c5..e4d5abae11 100644
--- a/guides/code/getting_started/test/functional/home_controller_test.rb
+++ b/guides/code/getting_started/test/functional/welcome_controller_test.rb
@@ -5,5 +5,4 @@ class WelcomeControllerTest < ActionController::TestCase
     get :index
     assert_response :success
   end
-
 end
diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile
index 2addc50d68..011a702901 100644
--- a/guides/source/active_support_core_extensions.textile
+++ b/guides/source/active_support_core_extensions.textile
@@ -156,7 +156,7 @@ NOTE: Defined in +active_support/core_ext/object/duplicable.rb+.
 
 h4. +deep_dup+
 
-The +deep_dup+ method returns deep copy of given object. Normally, when you +dup+ an object that contains other objects, ruby does not +dup+ them. If you have array with a string, for example, it will look like this:
+The +deep_dup+ method returns deep copy of a given object. Normally, when you +dup+ an object that contains other objects, ruby does not +dup+ them. If you have an array with a string, for example, it will look like this:
 
 <ruby>
 array     = ['string']
@@ -164,7 +164,7 @@ duplicate = array.dup
 
 duplicate.push 'another-string'
 
-# object was duplicated, element added only to duplicate
+# object was duplicated, so element was added only to duplicate
 array     #=> ['string']
 duplicate #=> ['string', 'another-string']
 
@@ -177,7 +177,7 @@ duplicate #=> ['foo', 'another-string']
 
 As you can see, after duplicating +Array+ instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since +dup+ does not make deep copy, the string inside array is still the same object.
 
-If you need a deep copy of an object, you should use +deep_dup+ in such situation:
+If you need a deep copy of an object, you should use +deep_dup+. Here is an example:
 
 <ruby>
 array     = ['string']
@@ -189,7 +189,7 @@ array     #=> ['string']
 duplicate #=> ['foo']
 </ruby>
 
-If object is not duplicable +deep_dup+ will just return this object:
+If object is not duplicable, +deep_dup+ will just return this object:
 
 <ruby>
 number = 1
@@ -201,9 +201,21 @@ NOTE: Defined in +active_support/core_ext/object/deep_dup.rb+.
 
 h4. +try+
 
-Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+.
+When you want to call a method on an object only if it is not +nil+, the simplest way to achieve it is with conditional statements, adding unnecessary clutter. The alternative is to use +try+. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+.
 
-For instance, in this code from +ActiveRecord::ConnectionAdapters::AbstractAdapter+ +@logger+ could be +nil+, but you save the check and write in an optimistic style:
+Here is an example:
+
+<ruby>
+# without try
+unless @number.nil?
+  @number.next
+end
+
+# with try
+@number.try(:next)
+</ruby>
+
+Another example is this code from +ActiveRecord::ConnectionAdapters::AbstractAdapter+ where +@logger+ could be +nil+. You can see that the code uses +try+ and avoids an unnecessary check.
 
 <ruby>
 def log_info(sql, name, ms)
@@ -245,7 +257,7 @@ NOTE: Defined in +active_support/core_ext/kernel/singleton_class.rb+.
 
 h4. +acts_like?(duck)+
 
-The method +acts_like+ provides a way to check whether some class acts like some other class based on a simple convention: a class that provides the same interface as +String+ defines
+The method +acts_like?+ provides a way to check whether some class acts like some other class based on a simple convention: a class that provides the same interface as +String+ defines
 
 <ruby>
 def acts_like_string?
diff --git a/guides/source/routing.textile b/guides/source/routing.textile
index 0773a96c67..7941e655bb 100644
--- a/guides/source/routing.textile
+++ b/guides/source/routing.textile
@@ -859,9 +859,11 @@ h3. Inspecting and Testing Routes
 
 Rails offers facilities for inspecting and testing your routes.
 
-h4. Seeing Existing Routes with +rake+
+h4. Seeing Existing Routes
 
-If you want a complete list of all of the available routes in your application, run +rake routes+ command. This will print all of your routes, in the same order that they appear in +routes.rb+. For each route, you'll see:
+To get a complete list of the available routes in your application, visit +http://localhost:3000/rails/info/routes+ in your browser while your server is running in the *development* environment. You can also execute the +rake routes+ command in your terminal to produce the same output.
+
+Both methods will list all of your routes, in the same order that they appear in +routes.rb+. For each route, you'll see:
 
 * The route name (if any)
 * The HTTP verb used (if the route doesn't respond to all verbs)