commit review: say clearly that AS::OrderedHash is about insertion order, be more neutral in wording, do not imply lack of ordering is a problem

activesupport/lib/active_support/ordered_hash.rb

@@ -4,15 +4,17 @@ YAML.add_builtin_type("omap") do |type, val|
   ActiveSupport::OrderedHash[val.map(&:to_a).map(&:first)]
 end
 
-# Hash is not ordered in ruby 1.8.x. What it means is there is no guarantee of order of keys when 
-# method Hash#keys in invoked. Similarly Hash#values and Hash#each can't guarantee that each time
-# the output will contain exactly same value in the same order. <tt>OrderedHash</tt> solves that
-# problem. 
-#   
-#   ActiveSupport::OrderedHash[:boy, 'John', :girl, 'Mary']
-#   
-# 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"

activesupport/lib/active_support/ordered_options.rb

@@ -5,16 +5,16 @@ require 'active_support/ordered_hash'
 #   h = ActiveSupport::OrderedOptions.new
 #   h[:boy] = 'John'
 #   h[:girl] = 'Mary'
-#   h[:boy]  #=> 'John'
+#   h[:boy]  # => 'John'
-#   h[:girl] #=> 'Mary'
+#   h[:girl] # => 'Mary'
 # 
 # Using <tt>OrderedOptions</tt> above code could be reduced to:
 #
 #   h = ActiveSupport::OrderedOptions.new
 #   h.boy = 'John'
 #   h.girl = 'Mary'
-#   h.boy  #=> 'John'
+#   h.boy  # => 'John'
-#   h.girl #=> 'Mary'
+#   h.girl # => 'Mary'
 # 
 module ActiveSupport #:nodoc:
   class OrderedOptions < OrderedHash