Merge docrails

11 files changed, 99 insertions, 8 deletions

diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb
index 8719dc0e3f..6727eda811 100644
--- a/activesupport/lib/active_support/callbacks.rb
+++ b/activesupport/lib/active_support/callbacks.rb
@@ -531,7 +531,7 @@ module ActiveSupport
       # to change this behavior.
       #
       # * <tt>:scope</tt> - Show which methods should be executed when a class
-      # is giben as callback:
+      # is given as callback:
       #
       #   define_callbacks :filters, :scope => [ :kind ]
       #
diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index d7606bb9b0..c69a015f12 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -4,7 +4,7 @@ class Array
   #   %w( a b c d ).from(0)  # => %w( a b c d )
   #   %w( a b c d ).from(2)  # => %w( c d )
   #   %w( a b c d ).from(10) # => nil
-  #   %w().from(0)           # => nil
+  #   %w().from(0)           # => %w()
   def from(position)
     self[position..-1]
   end
diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb
index f48d5ce500..e211bdeeca 100644
--- a/activesupport/lib/active_support/core_ext/array/wrap.rb
+++ b/activesupport/lib/active_support/core_ext/array/wrap.rb
@@ -1,6 +1,15 @@
 class Array
   # Wraps the object in an Array unless it's an Array.  Converts the
   # object to an Array using #to_ary if it implements that.
+  #
+  # It differs with Array() in that it does not call +to_a+ on
+  # the argument:
+  #
+  #   Array(:foo => :bar)      # => [[:foo, :bar]]
+  #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
+  #
+  #   Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
+  #   Array.wrap("foo\nbar")   # => ["foo\nbar"]
   def self.wrap(object)
     if object.nil?
       []
diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb
index cfd840fb93..48b185d05e 100644
--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -69,6 +69,54 @@ class Hash
     )
   end
 
+  # Returns a string containing an XML representation of its receiver:
+  # 
+  #   {"foo" => 1, "bar" => 2}.to_xml
+  #   # =>
+  #   # <?xml version="1.0" encoding="UTF-8"?>
+  #   # <hash>
+  #   #   <foo type="integer">1</foo>
+  #   #   <bar type="integer">2</bar>
+  #   # </hash>
+  # 
+  # To do so, the method loops over the pairs and builds nodes that depend on
+  # the _values_. Given a pair +key+, +value+:
+  # 
+  # * If +value+ is a hash there's a recursive call with +key+ as <tt>:root</tt>.
+  # 
+  # * If +value+ is an array there's a recursive call with +key+ as <tt>:root</tt>,
+  #   and +key+ singularized as <tt>:children</tt>.
+  # 
+  # * If +value+ is a callable object it must expect one or two arguments. Depending
+  #   on the arity, the callable is invoked with the +options+ hash as first argument
+  #   with +key+ as <tt>:root</tt>, and +key+ singularized as second argument. Its
+  #   return value becomes a new node.
+  # 
+  # * If +value+ responds to +to_xml+ the method is invoked with +key+ as <tt>:root</tt>.
+  # 
+  # * Otherwise, a node with +key+ as tag is created with a string representation of
+  #   +value+ as text node. If +value+ is +nil+ an attribute "nil" set to "true" is added.
+  #   Unless the option <tt>:skip_types</tt> exists and is true, an attribute "type" is
+  #   added as well according to the following mapping:
+  #
+  #     XML_TYPE_NAMES = {
+  #       "Symbol"     => "symbol",
+  #       "Fixnum"     => "integer",
+  #       "Bignum"     => "integer",
+  #       "BigDecimal" => "decimal",
+  #       "Float"      => "float",
+  #       "TrueClass"  => "boolean",
+  #       "FalseClass" => "boolean",
+  #       "Date"       => "date",
+  #       "DateTime"   => "datetime",
+  #       "Time"       => "datetime"
+  #     }
+  # 
+  # By default the root node is "hash", but that's configurable via the <tt>:root</tt> option.
+  # 
+  # The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can
+  # configure your own builder with the <tt>:builder</tt> option. The method also accepts
+  # options like <tt>:dasherize</tt> and friends, they are forwarded to the builder.
   def to_xml(options = {})
     require 'builder' unless defined?(Builder)
 
diff --git a/activesupport/lib/active_support/core_ext/hash/except.rb b/activesupport/lib/active_support/core_ext/hash/except.rb
index 6d04cb5621..207801d3a7 100644
--- a/activesupport/lib/active_support/core_ext/hash/except.rb
+++ b/activesupport/lib/active_support/core_ext/hash/except.rb
@@ -3,6 +3,14 @@ class Hash
   # limiting a set of parameters to everything but a few known toggles:
   #
   #   @person.update_attributes(params[:person].except(:admin))
+  #
+  # If the receiver responds to +convert_key+, the method is called on each of the
+  # arguments. This allows +except+ to play nice with hashes with indifferent access
+  # for instance:
+  #
+  #   {:a => 1}.with_indifferent_access.except(:a)  # => {}
+  #   {:a => 1}.with_indifferent_access.except("a") # => {}
+  #
   def except(*keys)
     dup.except!(*keys)
   end
diff --git a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
index b30e1602b6..0420e206af 100644
--- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
+++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
@@ -1,6 +1,11 @@
 require 'active_support/hash_with_indifferent_access'
 
 class Hash
+
+  # Returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver:
+  #
+  #   {:a => 1}.with_indifferent_access["a"] # => 1
+  #
   def with_indifferent_access
     hash = ActiveSupport::HashWithIndifferentAccess.new(self)
     hash.default = self.default
diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb
index ffaa69570f..ecd63293b4 100644
--- a/activesupport/lib/active_support/core_ext/hash/keys.rb
+++ b/activesupport/lib/active_support/core_ext/hash/keys.rb
@@ -15,7 +15,8 @@ class Hash
     self
   end
 
-  # Return a new hash with all keys converted to symbols.
+  # Return a new hash with all keys converted to symbols, as long as
+  # they respond to +to_sym+.
   def symbolize_keys
     inject({}) do |options, (key, value)|
       options[(key.to_sym rescue key) || key] = value
@@ -23,7 +24,8 @@ class Hash
     end
   end
 
-  # Destructively convert all keys to symbols.
+  # Destructively convert all keys to symbols, as long as they respond
+  # to +to_sym+.
   def symbolize_keys!
     self.replace(self.symbolize_keys)
   end
diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb
index a2d4d50076..b05325790c 100644
--- a/activesupport/lib/active_support/core_ext/object/duplicable.rb
+++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb
@@ -1,3 +1,19 @@
+# Most objects are cloneable, but not all. For example you can't dup +nil+:
+#
+#   nil.dup # => TypeError: can't dup NilClass
+#
+# Classes may signal their instances are not duplicable removing +dup+/+clone+
+# or raising exceptions from them. So, to dup an arbitrary object you normally
+# use an optimistic approach and are ready to catch an exception, say:
+#
+#   arbitrary_object.dup rescue object
+#
+# Rails dups objects in a few critical spots where they are not that arbitrary.
+# That rescue is very expensive (like 40 times slower than a predicate), and it
+# is often triggered.
+#
+# That's why we hardcode the following cases and check duplicable? instead of
+# using that rescue idiom.
 class Object
   # Can you safely .dup this object?
   # False for nil, false, true, symbols, numbers, class and module objects; true otherwise.
diff --git a/activesupport/lib/active_support/core_ext/rexml.rb b/activesupport/lib/active_support/core_ext/rexml.rb
index 5288b639a6..0419ebc84b 100644
--- a/activesupport/lib/active_support/core_ext/rexml.rb
+++ b/activesupport/lib/active_support/core_ext/rexml.rb
@@ -2,7 +2,10 @@ require 'active_support/core_ext/kernel/reporting'
 
 # Fixes the rexml vulnerability disclosed at:
 # http://www.ruby-lang.org/en/news/2008/08/23/dos-vulnerability-in-rexml/
-# This fix is identical to rexml-expansion-fix version 1.0.1
+# This fix is identical to rexml-expansion-fix version 1.0.1.
+#
+# We still need to distribute this fix because albeit the REXML
+# in recent 1.8.7s is patched, it wasn't in early patchlevels.
 require 'rexml/rexml'
 
 # Earlier versions of rexml defined REXML::Version, newer ones REXML::VERSION
diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb
index 182b3e745d..64bc8f6cea 100644
--- a/activesupport/lib/active_support/core_ext/string/access.rb
+++ b/activesupport/lib/active_support/core_ext/string/access.rb
@@ -7,7 +7,7 @@ class String
     # Examples: 
     #   "hello".at(0)  # => "h"
     #   "hello".at(4)  # => "o"
-    #   "hello".at(10) # => nil
+    #   "hello".at(10) # => ERROR if < 1.9, nil in 1.9
     def at(position)
       mb_chars[position, 1].to_s
     end
@@ -17,7 +17,7 @@ class String
     # Examples: 
     #   "hello".from(0)  # => "hello"
     #   "hello".from(2)  # => "llo"
-    #   "hello".from(10) # => nil
+    #   "hello".from(10) # => "" if < 1.9, nil in 1.9
     def from(position)
       mb_chars[position..-1].to_s
     end
diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb
index c7225fec06..3eb0bf31f8 100644
--- a/activesupport/lib/active_support/multibyte/chars.rb
+++ b/activesupport/lib/active_support/multibyte/chars.rb
@@ -385,7 +385,7 @@ module ActiveSupport #:nodoc:
       # Convert characters in the string to uppercase.
       #
       # Example:
-      #   'Laurent, òu sont les tests?'.mb_chars.upcase.to_s #=> "LAURENT, ÒU SONT LES TESTS?"
+      #   'Laurent, où sont les tests ?'.mb_chars.upcase.to_s #=> "LAURENT, OÙ SONT LES TESTS ?"
       def upcase
         apply_mapping :uppercase_mapping
       end