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

Conflicts:
	actionpack/lib/action_view/helpers/asset_tag_helper.rb

13 files changed, 44 insertions, 24 deletions

diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb
index 323126fcfa..3e36c54eba 100644
--- a/activesupport/lib/active_support/core_ext/date/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date/calculations.rb
@@ -107,8 +107,6 @@ class Date
 
   # Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
   #
-  # Examples:
-  #
   #   Date.new(2007, 5, 12).change(:day => 1)                  # => Date.new(2007, 5, 1)
   #   Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
   def change(options)
diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb
index 97e3c71992..81f969e786 100644
--- a/activesupport/lib/active_support/core_ext/date/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date/conversions.rb
@@ -26,7 +26,6 @@ class Date
   #
   # This method is aliased to <tt>to_s</tt>.
   #
-  # ==== Examples
   #   date = Date.new(2007, 11, 10)       # => Sat, 10 Nov 2007
   #
   #   date.to_formatted_s(:db)            # => "2007-11-10"
@@ -69,7 +68,6 @@ class Date
   # Converts a Date instance to a Time, where the time is set to the beginning of the day.
   # The timezone can be either :local or :utc (default :local).
   #
-  # ==== Examples
   #   date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007
   #
   #   date.to_time                   # => Sat Nov 10 00:00:00 0800 2007
diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
index 020fa1a06d..fd78044b5d 100644
--- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb
@@ -104,8 +104,6 @@ class DateTime
 
   # Adjusts DateTime to UTC by adding its offset value; offset is set to 0
   #
-  # Example:
-  #
   #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24))       # => Mon, 21 Feb 2005 10:11:12 -0600
   #   DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc   # => Mon, 21 Feb 2005 16:11:12 +0000
   def utc
diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
index 6338dc6397..19925198c0 100644
--- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb
@@ -42,7 +42,6 @@ class DateTime
   alias_method :to_default_s, :to_s unless (instance_methods(false) & [:to_s, 'to_s']).empty?
   alias_method :to_s, :to_formatted_s
 
-  # Returns the +utc_offset+ as an +HH:MM formatted string. Examples:
   #
   #   datetime = DateTime.civil(2000, 1, 1, 0, 0, 0, Rational(-6, 24))
   #   datetime.formatted_offset         # => "-06:00"
diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb
index b9c632e4f5..02d5a7080f 100644
--- a/activesupport/lib/active_support/core_ext/enumerable.rb
+++ b/activesupport/lib/active_support/core_ext/enumerable.rb
@@ -1,5 +1,5 @@
 module Enumerable
-  # Calculates a sum from the elements. Examples:
+  # Calculates a sum from the elements.
   #
   #  payments.sum { |p| p.price * p.tax_rate }
   #  payments.sum(&:price)
@@ -26,7 +26,7 @@ module Enumerable
     end
   end
 
-  # Convert an enumerable to a hash. Examples:
+  # Convert an enumerable to a hash.
   #
   #   people.index_by(&:login)
   #     => { "nextangle" => <Person ...>, "chade-" => <Person ...>, ...}
diff --git a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
index af771c86ff..023bf68a87 100644
--- a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
@@ -1,11 +1,16 @@
 class Hash
   # Returns a new hash with +self+ and +other_hash+ merged recursively.
+  #
+  #   h1 = {x: {y: [4,5,6]}, z: [7,8,9]}
+  #   h2 = {x: {y: [7,8,9]}, z: "xyz"}
+  #
+  #   h1.deep_merge(h2) #=> {:x => {:y => [7, 8, 9]}, :z => "xyz"}
+  #   h2.deep_merge(h1) #=> {:x => {:y => [4, 5, 6]}, :z => [7, 8, 9]}
   def deep_merge(other_hash)
     dup.deep_merge!(other_hash)
   end
 
-  # Returns a new hash with +self+ and +other_hash+ merged recursively.
-  # Modifies the receiver in place.
+  # Same as +deep_merge+, but modifies +self+.
   def deep_merge!(other_hash)
     other_hash.each_pair do |k,v|
       tv = self[k]
diff --git a/activesupport/lib/active_support/core_ext/hash/diff.rb b/activesupport/lib/active_support/core_ext/hash/diff.rb
index 855dcb38bc..831dee8ecb 100644
--- a/activesupport/lib/active_support/core_ext/hash/diff.rb
+++ b/activesupport/lib/active_support/core_ext/hash/diff.rb
@@ -1,8 +1,6 @@
 class Hash
   # Returns a hash that represents the difference between two hashes.
   #
-  # Examples:
-  #
   #   {1 => 2}.diff(1 => 2)         # => {}
   #   {1 => 2}.diff(1 => 3)         # => {1 => 2}
   #   {}.diff(1 => 2)               # => {1 => 2}
diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb
index 230a84dabc..be4d611ce7 100644
--- a/activesupport/lib/active_support/core_ext/hash/keys.rb
+++ b/activesupport/lib/active_support/core_ext/hash/keys.rb
@@ -1,5 +1,8 @@
 class Hash
   # Return a new hash with all keys converted to strings.
+  #
+  #   { :name => 'Rob', :years => '28' }.stringify_keys
+  #   #=> { "name" => "Rob", "years" => "28" }
   def stringify_keys
     result = {}
     keys.each do |key|
@@ -8,7 +11,8 @@ class Hash
     result
   end
 
-  # Destructively convert all keys to strings.
+  # Destructively convert all keys to strings. Same as
+  # +stringify_keys+, but modifies +self+.
   def stringify_keys!
     keys.each do |key|
       self[key.to_s] = delete(key)
@@ -18,6 +22,9 @@ class Hash
 
   # Return a new hash with all keys converted to symbols, as long as
   # they respond to +to_sym+.
+  #
+  #   { 'name' => 'Rob', 'years' => '28' }.symbolize_keys
+  #   #=> { :name => "Rob", :years => "28" }
   def symbolize_keys
     result = {}
     keys.each do |key|
@@ -28,7 +35,7 @@ class Hash
   alias_method :to_options,  :symbolize_keys
 
   # Destructively convert all keys to symbols, as long as they respond
-  # to +to_sym+.
+  # to +to_sym+. Same as +symbolize_keys+, but modifies +self+.
   def symbolize_keys!
     keys.each do |key|
       self[(key.to_sym rescue key)] = delete(key)
@@ -41,7 +48,6 @@ class Hash
   # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols
   # as keys, this will fail.
   #
-  # ==== Examples
   #   { :name => 'Rob', :years => '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years"
   #   { :name => 'Rob', :age => '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name"
   #   { :name => 'Rob', :age => '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing
diff --git a/activesupport/lib/active_support/core_ext/module/aliasing.rb b/activesupport/lib/active_support/core_ext/module/aliasing.rb
index 382156ecd8..580cb80413 100644
--- a/activesupport/lib/active_support/core_ext/module/aliasing.rb
+++ b/activesupport/lib/active_support/core_ext/module/aliasing.rb
@@ -45,8 +45,6 @@ class Module
   # Allows you to make aliases for attributes, which includes
   # getter, setter, and query methods.
   #
-  # Example:
-  #
   #   class Content < ActiveRecord::Base
   #     # has a title attribute
   #   end
diff --git a/activesupport/lib/active_support/core_ext/object/deep_dup.rb b/activesupport/lib/active_support/core_ext/object/deep_dup.rb
index 2c4383ac94..883f5f556c 100644
--- a/activesupport/lib/active_support/core_ext/object/deep_dup.rb
+++ b/activesupport/lib/active_support/core_ext/object/deep_dup.rb
@@ -1,5 +1,13 @@
 class Object
-  # Returns a deep copy of object if it's duplicable.
+  # Returns a deep copy of object if it's duplicable. If it's
+  # not duplicable, returns +self+.
+  #
+  #   object = Object.new
+  #   dup    = object.deep_dup
+  #   dup.instance_variable_set(:@a, 1)
+  #
+  #   object.instance_variable_defined?(:@a) #=> false
+  #   dup.instance_variable_defined?(:@a)    #=> true
   def deep_dup
     duplicable? ? dup : self
   end
@@ -7,6 +15,13 @@ end
 
 class Array
   # Returns a deep copy of array.
+  #
+  #   array = [1, [2, 3]]
+  #   dup   = array.deep_dup
+  #   dup[1][2] = 4
+  #
+  #   array[1][2] #=> nil
+  #   dup[1][2]   #=> 4
   def deep_dup
     map { |it| it.deep_dup }
   end
@@ -14,6 +29,13 @@ end
 
 class Hash
   # Returns a deep copy of hash.
+  #
+  #   hash = { a: { b: 'b' } }
+  #   dup  = hash.deep_dup
+  #   dup[:a][:c] = 'c'
+  #
+  #   hash[:a][:c] #=> nil
+  #   dup[:a][:c]  #=> "c"
   def deep_dup
     each_with_object(dup) do |(key, value), hash|
       hash[key.deep_dup] = value.deep_dup
diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb
index 40a8101ca3..48eb546a7d 100644
--- a/activesupport/lib/active_support/core_ext/object/try.rb
+++ b/activesupport/lib/active_support/core_ext/object/try.rb
@@ -1,6 +1,6 @@
 class Object
   # Invokes the public method identified by the symbol +method+, passing it any arguments
-  # and/or the block specified, just like the regular Ruby <tt>Object#send</tt> does.
+  # and/or the block specified, just like the regular Ruby <tt>Object#public_send</tt> does.
   #
   # *Unlike* that method however, a +NoMethodError+ exception will *not* be raised
   # and +nil+ will be returned instead, if the receiving object is a +nil+ object or NilClass.
@@ -24,7 +24,7 @@ class Object
   # Without a method argument try will yield to the block unless the receiver is nil.
   #   @person.try { |p| "#{p.first_name} #{p.last_name}" }
   #--
-  # +try+ behaves like +Object#send+, unless called on +NilClass+.
+  # +try+ behaves like +Object#public_send+, unless called on +NilClass+.
   def try(*a, &b)
     if a.empty? && block_given?
       yield self
diff --git a/activesupport/lib/active_support/core_ext/range/conversions.rb b/activesupport/lib/active_support/core_ext/range/conversions.rb
index 43134b4314..b1a12781f3 100644
--- a/activesupport/lib/active_support/core_ext/range/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/range/conversions.rb
@@ -5,8 +5,6 @@ class Range
 
   # Gives a human readable format of the range.
   #
-  # ==== Example
-  #
   #   (1..100).to_formatted_s # => "1..100"
   def to_formatted_s(format = :default)
     if formatter = RANGE_FORMATS[format]
diff --git a/activesupport/lib/active_support/core_ext/string/inquiry.rb b/activesupport/lib/active_support/core_ext/string/inquiry.rb
index 2562a7cef6..1dcd949536 100644
--- a/activesupport/lib/active_support/core_ext/string/inquiry.rb
+++ b/activesupport/lib/active_support/core_ext/string/inquiry.rb
@@ -2,7 +2,7 @@ require 'active_support/string_inquirer'
 
 class String
   # Wraps the current string in the <tt>ActiveSupport::StringInquirer</tt> class,
-  # which gives you a prettier way to test for equality. Example:
+  # which gives you a prettier way to test for equality.
   #
   #   env = 'production'.inquiry
   #   env.production?  # => true