Merge branch 'master' of http://github.com/rails/rails

1 files changed, 10 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/ordered_hash.rb b/activesupport/lib/active_support/ordered_hash.rb
index 6b563b9063..2e8d538d0b 100644
--- a/activesupport/lib/active_support/ordered_hash.rb
+++ b/activesupport/lib/active_support/ordered_hash.rb
@@ -4,8 +4,17 @@ YAML.add_builtin_type("omap") do |type, val|
   ActiveSupport::OrderedHash[val.map(&:to_a).map(&:first)]
 end
 
-# OrderedHash is namespaced to prevent conflicts with other implementations
 module ActiveSupport
+  # The order of iteration over hashes in Ruby 1.8 is undefined. For example, you do not know the
+  # order in which +keys+ will return keys, or +each+ yield pairs. <tt>ActiveSupport::OrderedHash</tt>
+  # implements a hash that preserves insertion order, as in Ruby 1.9:
+  #   
+  #   oh = ActiveSupport::OrderedHash.new
+  #   oh[:a] = 1
+  #   oh[:b] = 2
+  #   oh.keys # => [:a, :b], this order is guaranteed
+  #   
+  # <tt>ActiveSupport::OrderedHash</tt> is namespaced to prevent conflicts with other implementations.
   class OrderedHash < ::Hash #:nodoc:
     def to_yaml_type
       "!tag:yaml.org,2002:omap"