https://git.ruby-lang.org/ruby.git/commit/?id=d469807980

From d46980798043463fa0622be3d787d5cda829cb37 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Fri, 15 May 2020 16:11:42 -0500
Subject:  [CI skip] Enhance rdoc intro for Hash  (#3056)

* Per @nobu review

* [CI skip] Enhance rdoc intro for Hash

* Tweak call-seq for Hash.new

* Tweak call-seq for Hash.new

* Minor corrections

* Respond to review

* Respond to review

* Respond to review

* Respond to review

* Fix chain exampmle

* Response to review

diff --git a/doc/implicit_conversion.rdoc b/doc/implicit_conversion.rdoc
index fae5973..0c2a1d4 100644
--- a/doc/implicit_conversion.rdoc
+++ b/doc/implicit_conversion.rdoc
@@ -28,7 +28,7 @@ This class is Array-convertible: https://github.com/ruby/ruby/blob/trunk/doc/implicit_conversion.rdoc#L28
 
     class ArrayConvertible
       def to_ary
-        [:foo, 'bar', baz = 2]
+        [:foo, 'bar', 2]
       end
     end
     a = []
@@ -45,7 +45,7 @@ This class is not Array-convertible (method +to_ary+ takes arguments): https://github.com/ruby/ruby/blob/trunk/doc/implicit_conversion.rdoc#L45
 
     class NotArrayConvertible
       def to_ary(x)
-        [:foo, 'bar', baz = 2]
+        [:foo, 'bar', 2]
       end
     end
     a = []
diff --git a/hash.c b/hash.c
index b7d320f..5e42b70 100644
--- a/hash.c
+++ b/hash.c
@@ -1749,9 +1749,9 @@ set_proc_default(VALUE hash, VALUE proc) https://github.com/ruby/ruby/blob/trunk/hash.c#L1749
 
 /*
  *  call-seq:
- *     Hash.new                          -> new_hash
- *     Hash.new(default_value)           -> new_hash
- *     Hash.new {|hash, key| block }     -> new_hash
+ *     Hash.new                                        -> new_hash
+ *     Hash.new(default_value)                         -> new_hash
+ *     Hash.new{|hash, key| hash[key] = default_value} -> new_hash
  *
  *  Returns a new empty Hash object.
  *
@@ -1786,9 +1786,12 @@ set_proc_default(VALUE hash, VALUE proc) https://github.com/ruby/ruby/blob/trunk/hash.c#L1786
  *    h.default_proc.class # => Proc
  *    h[:nosuch] # => "Default value for nosuch"
  *
+ *  ---
+ *
  *  Raises an exception if both argument <tt>default_value</tt> and a block are given:
  *
- *    Hash.new(0) { } # Raises ArgumentError (wrong number of arguments (given 1, expected 0)) *
+ *    # Raises ArgumentError (wrong number of arguments (given 1, expected 0)):
+ *    Hash.new(0) { }
  */
 
 static VALUE
@@ -1860,27 +1863,35 @@ rb_hash_initialize(int argc, VALUE *argv, VALUE hash) https://github.com/ruby/ruby/blob/trunk/hash.c#L1863
  *  but the argument is not an array of 2-element arrays or a
  *  {Hash-convertible object}[doc/implicit_conversion_rdoc.html#label-Hash-Convertible+Objects]:
  *
- *    Hash[:foo] # Raises ArgumentError (odd number of arguments
- *    Hash[ [ [:foo, 0, 1] ] ] # Raises ArgumentError (invalid number of elements (3 for 1..2))
+ *    # Raises ArgumentError (odd number of arguments for Hash):
+ *    Hash[:foo]
+ *    # Raises ArgumentError (invalid number of elements (3 for 1..2)):
+ *    Hash[ [ [:foo, 0, 1] ] ]
  *
  *  Raises an exception if the argument count is odd and greater than 1:
  *
- *    Hash[0, 1, 2] # Raises ArgumentError (odd number of arguments for Hash)
+ *    # Raises ArgumentError (odd number of arguments for Hash):
+ *    Hash[0, 1, 2]
  *
  *  Raises an exception if the argument is an array containing an element
  *  that is not a 2-element array:
  *
- *    Hash[ [ :foo ] ] # Raises ArgumentError (wrong element type Symbol at 0 (expected array))
+ *    # Raises ArgumentError (wrong element type Symbol at 0 (expected array)):
+ *    Hash[ [ :foo ] ]
  *
  *  Raises an exception if the argument is an array containing an element
  *  that is an array of size different from 2:
  *
- *    Hash[ [ [0, 1, 2] ] ] # Raises ArgumentError (invalid number of elements (3 for 1..2))
+ *    # Raises ArgumentError (invalid number of elements (3 for 1..2)):
+ *    Hash[ [ [0, 1, 2] ] ]
  *
- *  Raises an exception if any proposed key is not a valid key:
+ *  Raises an exception if any proposed key is not a valid key
+ *  (see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]):
  *
- *    Hash[:foo, 0, BasicObject.new, 1] # Raises NoMethodError (undefined method `hash' for #<BasicObject:>)
- *    Hash[ [ [:foo, 0], [BasicObject.new, 1] ] ] # Raises NoMethodError (undefined method `hash' for #<BasicObject:0x00000000064b1328>)
+ *    # Raises NoMethodError (undefined method `hash' for #<BasicObject:>):
+ *    Hash[:foo, 0, BasicObject.new, 1]
+ *    # Raises NoMethodError (undefined method `hash' for #<BasicObject:>):
+ *    Hash[ [ [:foo, 0], [BasicObject.new, 1] ] ]
  */
 
 static VALUE
@@ -2047,22 +2058,22 @@ rb_hash_rehash_i(VALUE key, VALUE value, VALUE arg) https://github.com/ruby/ruby/blob/trunk/hash.c#L2058
 
 /*
  *  call-seq:
- *     hsh.rehash -> hsh
- *
- *  Rebuilds the hash based on the current hash values for each key. If
- *  values of key objects have changed since they were inserted, this
- *  method will reindex <i>hsh</i>. If Hash#rehash is
- *  called while an iterator is traversing the hash, a
- *  RuntimeError will be raised in the iterator.
- *
- *     a = [ "a", "b" ]
- *     c = [ "c", "d" ]
- *     h = { a => 100, c => 300 }
- *     h[a]       #=> 100
- *     a[0] = "z"
- *     h[a]       #=> nil
- *     h.rehash   #=> {["z", "b"]=>100, ["c", "d"]=>300}
- *     h[a]       #=> 100
+ *     hsh.rehash -> self
+ *
+ *  Rebuilds the hash table by recomputing the hash index for each key;
+ *  returns <tt>self</tt>.
+ *
+ *  The hash table will have become invalid if the hash value of a key
+ *  has changed since the entry was created.
+ *  See {Modifying an Active Hash Key}[#class-Hash-label-Modifying+an+Active+Hash+Key].
+ *
+ *  ---
+ *
+ *  Raises an exception if called while an iterator is traversing the hash:
+ *
+ *    h = {foo: 0, bar: 1, baz: 2}
+ *    # Raises RuntimeError (rehash during iteration):
+ *    h.each { |x| h.rehash }
  */
 
 VALUE
@@ -6532,68 +6543,229 @@ env_update(VALUE env, VALUE hash) https://github.com/ruby/ruby/blob/trunk/hash.c#L6543
 }
 
 /*
- *  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 maps each of its unique keys to a specific value.
  *
- *  A Hash can be easily created by using its implicit form:
+ *  A \Hash has certain similarities to an \Array, but:
+ *  - An \Array index is always an \Integer.
+ *  - A \Hash key can be (almost) any object.
  *
- *    grades = { "Jane Doe" => 10, "Jim Doe" => 6 }
+ *  === \Hash \Data Syntax
  *
- *  Hashes allow an alternate syntax for keys that are symbols.
- *  Instead of
+ *  The older syntax for \Hash data uses the "hash rocket," <tt>=></tt>:
  *
- *    options = { :font_size => 10, :font_family => "Arial" }
+ *    h = {:foo => 0, :bar => 1, :baz => 2}
+ *    h # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *  You could write it as:
+ *  Alternatively, but only for a \Hash key that's a \Symbol,
+ *  you can use a newer JSON-style syntax,
+ *  where each bareword becomes a \Symbol:
  *
- *    options = { font_size: 10, font_family: "Arial" }
+ *    h = {foo: 0, bar: 1, baz: 2}
+ *    h # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *  Each named key is a symbol you can access in hash:
+ *  You can also use a \String in place of a bareword:
  *
- *    options[:font_size]  # => 10
+ *    h = {'foo': 0, 'bar': 1, 'baz': 2}
+ *    h # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *  A Hash can also be created through its ::new method:
+ *  And you can mix the styles:
  *
- *    grades = Hash.new
- *    grades["Dorothy Doe"] = 9
+ *    h = {foo: 0, :bar => 1, 'baz': 2}
+ *    h # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *  Accessing a value in a Hash requires using its key:
+ *  But it's an error to try the JSON-style syntax
+ *  for a key that's not a bareword or a String:
  *
- *    puts grades["Jane Doe"] # => 0
+ *    # Raises SyntaxError (syntax error, unexpected ':', expecting =>):
+ *    h = {0: 'zero'}
  *
  *  === Common Uses
  *
- *  Hashes are an easy way to represent data structures, such as
+ *  You can use a \Hash to give names to objects:
  *
- *    books         = {}
- *    books[:matz]  = "The Ruby Programming Language"
- *    books[:black] = "The Well-Grounded Rubyist"
+ *    person = {name: 'Matz', language: 'Ruby'}
+ *    person # => {:name=>"Matz", :language=>"Ruby"}
  *
- *  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:
+ *  You can use a \Hash to give names to method arguments:
+ *
+ *    def some_method(hash)
+ *      p hash
+ *    end
+ *    some_method({foo: 0, bar: 1, baz: 2}) # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *    Person.create(name: "John Doe", age: 27)
+ *  Note: when the last argument in a method call is a \Hash,
+ *  the curly braces may be omitted:
  *
- *    def self.create(params)
- *      @name = params[:name]
- *      @age  = params[:age]
+ *    some_method(foo: 0, bar: 1, baz: 2) # => {:foo=>0, :bar=>1, :baz=>2}
+ *
+ *  You can use a Hash to initialize an object:
+ *
+ *    class Dev
+ *      attr_accessor :name, :language
+ *      def initialize(hash)
+ *        self.name = hash[:name]
+ *        self.language = hash[:language]
+ *      end
  *    end
+ *    matz = Dev.new(name: 'Matz', language: 'Ruby')
+ *    matz # => #<Dev: @name="Matz", @language="Ruby">
+ *
+ *  === Creating a \Hash
+ *
+ *  Here are three ways to create a \Hash:
+ *
+ *  - \Method <tt>Hash.new</tt>
+ *  - \Method <tt>Hash[]</tt>
+ *  - Literal form: <tt>{}</tt>.
+ *
+ *  ---
+ *
+ *  You can create a \Hash by calling method Hash.new.
+ *
+ *  Create  (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/