adding documentation for OrderedHash and OrderedOptions

2 files changed, 24 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/ordered_hash.rb b/activesupport/lib/active_support/ordered_hash.rb
index 6b563b9063..e19d9d7dc1 100644
--- a/activesupport/lib/active_support/ordered_hash.rb
+++ b/activesupport/lib/active_support/ordered_hash.rb
@@ -4,7 +4,14 @@ 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
+# 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
diff --git a/activesupport/lib/active_support/ordered_options.rb b/activesupport/lib/active_support/ordered_options.rb
index 61ccb79211..b0584072c1 100644
--- a/activesupport/lib/active_support/ordered_options.rb
+++ b/activesupport/lib/active_support/ordered_options.rb
@@ -1,5 +1,21 @@
 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)