From ca9413674ea70dc67ab517734af2e40dac21beef Mon Sep 17 00:00:00 2001
From: Pratik Naik <pratiknaik@gmail.com>
Date: Wed, 26 Mar 2008 12:27:52 +0000
Subject: Improve documentation.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
---
 .../core_ext/hash/indifferent_access.rb            | 36 ++++++++++++++++++++++
 .../active_support/core_ext/hash/reverse_merge.rb  |  3 ++
 2 files changed, 39 insertions(+)

(limited to 'activesupport/lib/active_support/core_ext/hash')

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 fda0489e76..2213b09144 100644
--- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
+++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
@@ -1,5 +1,6 @@
 # This class has dubious semantics and we only have it so that
 # people can write params[:key] instead of params['key']
+# and they get the same value for both keys.
 
 class HashWithIndifferentAccess < Hash
   def initialize(constructor = {})
@@ -22,10 +23,38 @@ class HashWithIndifferentAccess < Hash
   alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
   alias_method :regular_update, :update unless method_defined?(:regular_update)
 
+  #
+  # Assigns a new value to the hash.
+  #
+  # Example:
+  #
+  #   hash = HashWithIndifferentAccess.new
+  #   hash[:key] = "value"
+  #
   def []=(key, value)
     regular_writer(convert_key(key), convert_value(value))
   end
 
+  # 
+  # Updates the instantized hash with values from the second.
+  # 
+  # Example:
+  # 
+  #   >> hash_1 = HashWithIndifferentAccess.new
+  #   => {}
+  # 
+  #   >> hash_1[:key] = "value"
+  #   => "value"
+  # 
+  #   >> hash_2 = HashWithIndifferentAccess.new
+  #   => {}
+  # 
+  #   >> hash_2[:key] = "New Value!"
+  #   => "New Value!"
+  # 
+  #   >> hash_1.update(hash_2)
+  #   => {"key"=>"New Value!"}
+  # 
   def update(other_hash)
     other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) }
     self
@@ -33,6 +62,7 @@ class HashWithIndifferentAccess < Hash
 
   alias_method :merge!, :update
 
+  # Checks the hash for a key matching the argument passed in
   def key?(key)
     super(convert_key(key))
   end
@@ -41,22 +71,28 @@ class HashWithIndifferentAccess < Hash
   alias_method :has_key?, :key?
   alias_method :member?, :key?
 
+  # Fetches the value for the specified key, same as doing hash[key]
   def fetch(key, *extras)
     super(convert_key(key), *extras)
   end
 
+  # Returns an array of the values at the specified indicies. 
   def values_at(*indices)
     indices.collect {|key| self[convert_key(key)]}
   end
 
+  # Returns an exact copy of the hash.
   def dup
     HashWithIndifferentAccess.new(self)
   end
 
+  # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash
+  # Does not overwrite the existing hash.
   def merge(hash)
     self.dup.update(hash)
   end
 
+  # Removes a specified key from the hash.
   def delete(key)
     super(convert_key(key))
   end
diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
index 3c4908ac9e..0ec0538024 100644
--- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
+++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb
@@ -10,10 +10,13 @@ module ActiveSupport #:nodoc:
       #
       # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set.
       module ReverseMerge
+        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
         def reverse_merge(other_hash)
           other_hash.merge(self)
         end
 
+        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
+        # Modifies the receiver in place.
         def reverse_merge!(other_hash)
           replace(reverse_merge(other_hash))
         end
-- 
cgit v1.2.3