adding documentation for OrderedHash and OrderedOptions

activesupport/lib/active_support/ordered_hash.rb

@@ -4,7 +4,14 @@
   ActiveSupport::OrderedHash[val.map(&:to_a).map(&:first)]
 end
 
-# OrderedHash is namespaced to prevent conflicts with other implementations
+# 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
   class OrderedHash < ::Hash #:nodoc:
     def to_yaml_type

activesupport/lib/active_support/ordered_options.rb

 require 'active_support/ordered_hash'
 
+# Usually key value pairs are handled something like this:
+#   
+#   h = ActiveSupport::OrderedOptions.new
+#   h[:boy] = 'John'
+#   h[:girl] = 'Mary'
+#   h[:boy]  #=> 'John'
+#   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.girl #=> 'Mary'
+# 
 module ActiveSupport #:nodoc:
   class OrderedOptions < OrderedHash
     def []=(key, value)