* hash.c (Init_Hash): Improve Hash documentation. Patch by Alvaro

  Pereyra Rabanal.  [Ruby 1.9 - Bug ruby#5405]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33406 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Wed Oct  5 05:56:39 2011  Eric Hodel  <[email protected]>
+
+	* hash.c (Init_Hash):  Improve Hash documentation.  Patch by Alvaro
+	  Pereyra Rabanal.  [Ruby 1.9 - Bug #5405]
+
 Wed Oct  5 05:47:59 2011  Eric Hodel  <[email protected]>
 
 	* random.c (Init_Random):  Add a top-level comment for Random.  Patch

hash.c

@@ -3150,14 +3150,70 @@ env_update(VALUE env, VALUE hash)
 }
 
 /*
- *  A <code>Hash</code> is a collection of key-value pairs. It is
- *  similar to an <code>Array</code>, except that indexing is done via
- *  arbitrary keys of any object type, not an integer index. Hashes enumerate
- *  their values in the order that the corresponding keys were inserted.
+ *  A Hash is a dictionary-like collection of unique keys and their values.
+ *  Also called associative arrays, they are similar to Arrays, but where an
+ *  Array uses integers as its index, a Hash allows you to use any object
+ *  type. 
+ *
+ *  Hashes enumerate their values in the order that the corresponding keys
+ *  were inserted. 
+ *
+ *  A Hash can be easily created by using its implicit form:
+ *
+ *    grades = { "Jane Doe" => 10, "Jim Doe" => 6 }
+ *  
+ *  Hashes allow an alternate syntax form when your keys are always symbols.
+ *  Instead of 
+ *
+ *    options = { :font_size => 10, :font_family => "Arial" }
+ * 
+ *  You could write it as: 
+ *
+ *    options = { font_size: 10, font_family: "Arial" }
+ * 
+ *  Each named key is a symbol you can access in hash:
+ *
+ *    options[:font_size]  # => 10
+ *
+ *  A Hash can also be created through its ::new method:
+ *
+ *    grades = Hash.new
+ *    grades["Dorothy Doe"] = 9
  *
  *  Hashes have a <em>default value</em> that is returned when accessing
- *  keys that do not exist in the hash. By default, that value is
- *  <code>nil</code>.
+ *  keys that do not exist in the hash. If no default is set +nil+ is used.
+ *  You can set the default value by sending it as an argument to Hash.new: 
+ *
+ *    grades = Hash.new(0)
+ *
+ *  Or by using the #default= method:
+ *
+ *    grades = {"Timmy Doe" => 8}
+ *    grades.default = 0
+ *     
+ *  Accessing a value in a Hash requires using its key:
+ *
+ *    puts grades["Jane Doe"] # => 10
+ *   
+ *  === Common Uses
+ *
+ *  Hashes are an easy way to represent data structures, such as
+ *
+ *    books         = {}
+ *    books[:matz]  = "The Ruby Language"
+ *    books[:black] = "The Well-Grounded Rubyist"
+ * 
+ *  Hashes are also commonly used as a way to have named parameters in
+ *  functions. Note that no brackets are used below. If a hash is the last
+ *  argument on a method call, no braces are needed, thus creating a really
+ *  clean interface: 
+ *  
+ *    Person.create(name: "John Doe", age: 27)
+ *
+ *    def self.create(params)
+ *      @name = params[:name]
+ *      @age  = params[:age]
+ *    end
  *
  */