Improve documentation.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 36 insertions, 0 deletions

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