[DOC] Tweaks for Hash#flatten

Merged: https://github.com/ruby/ruby/pull/12792

Merged-By: peterzhu2118 <peter@peterzhu.ca>

hash.c

@@ -4285,33 +4285,38 @@ flatten_i(VALUE key, VALUE val, VALUE ary)
 
 /*
  *  call-seq:
- *     flatten -> new_array
+ *    flatten(depth = 1) -> new_array
- *     flatten(level) -> new_array
  *
- *  Returns a new Array object that is a 1-dimensional flattening of +self+.
+ *  With positive integer +depth+,
+ *  returns a new array that is a recursive flattening of +self+ to the given +depth+.
  *
- *  ---
+ *  At each level of recursion:
  *
- *  By default, nested Arrays are not flattened:
+ *  - Each element whose value is an array is "flattened" (that is, replaced by its individual array elements);
- *    h = {foo: 0, bar: [:bat, 3], baz: 2}
+ *    see Array#flatten.
- *    h.flatten # => [:foo, 0, :bar, [:bat, 3], :baz, 2]
+ *  - Each element whose value is not an array is unchanged.
+ *    even if the value is an object that has instance method flatten (such as a hash).
  *
- *  Takes the depth of recursive flattening from Integer argument +level+:
+ *  Examples; note that entry <tt>foo: {bar: 1, baz: 2}</tt> is never flattened.
- *    h = {foo: 0, bar: [:bat, [:baz, [:bat, ]]]}
- *    h.flatten(1) # => [:foo, 0, :bar, [:bat, [:baz, [:bat]]]]
- *    h.flatten(2) # => [:foo, 0, :bar, :bat, [:baz, [:bat]]]
- *    h.flatten(3) # => [:foo, 0, :bar, :bat, :baz, [:bat]]
- *    h.flatten(4) # => [:foo, 0, :bar, :bat, :baz, :bat]
  *
- *  When +level+ is negative, flattens all nested Arrays:
+ *   h = {foo: {bar: 1, baz: 2}, bat: [:bam, [:bap, [:bah]]]}
- *    h = {foo: 0, bar: [:bat, [:baz, [:bat, ]]]}
+ *   h.flatten(1) # => [:foo, {:bar=>1, :baz=>2}, :bat, [:bam, [:bap, [:bah]]]]
- *    h.flatten(-1) # => [:foo, 0, :bar, :bat, :baz, :bat]
+ *   h.flatten(2) # => [:foo, {:bar=>1, :baz=>2}, :bat, :bam, [:bap, [:bah]]]
- *    h.flatten(-2) # => [:foo, 0, :bar, :bat, :baz, :bat]
+ *   h.flatten(3) # => [:foo, {:bar=>1, :baz=>2}, :bat, :bam, :bap, [:bah]]
+ *   h.flatten(4) # => [:foo, {:bar=>1, :baz=>2}, :bat, :bam, :bap, :bah]
+ *   h.flatten(5) # => [:foo, {:bar=>1, :baz=>2}, :bat, :bam, :bap, :bah]
  *
- *  When +level+ is zero, returns the equivalent of #to_a :
+ *  With negative integer +depth+,
- *    h = {foo: 0, bar: [:bat, 3], baz: 2}
+ *  flattens all levels:
- *    h.flatten(0) # => [[:foo, 0], [:bar, [:bat, 3]], [:baz, 2]]
+ *
- *    h.flatten(0) == h.to_a # => true
+ *    h.flatten(-1) # => [:foo, {:bar=>1, :baz=>2}, :bat, :bam, :bap, :bah]
+ *
+ *  With +depth+ zero,
+ *  returns the equivalent of #to_a:
+ *
+ *    h.flatten(0) # => [[:foo, {:bar=>1, :baz=>2}], [:bat, [:bam, [:bap, [:bah]]]]]
+ *
+ *  Related: see {Methods for Converting}[rdoc-ref:Hash@Methods+for+Converting].
  */
 
 static VALUE
@@ -7076,7 +7081,6 @@ static const rb_data_type_t env_data_type = {
  *  - {Iterating}[rdoc-ref:Hash@Methods+for+Iterating]
  *  - {Converting}[rdoc-ref:Hash@Methods+for+Converting]
  *  - {Transforming Keys and Values}[rdoc-ref:Hash@Methods+for+Transforming+Keys+and+Values]
- *  - {And more....}[rdoc-ref:Hash@Other+Methods]
  *
  *  Class +Hash+ also includes methods from module Enumerable.
  *
@@ -7164,6 +7168,7 @@ static const rb_data_type_t env_data_type = {
  *
  *  ==== Methods for Converting
  *
+ *  - #flatten: Returns an array that is a 1-dimensional flattening of +self+.
  *  - #inspect (aliased as #to_s): Returns a new String containing the hash entries.
  *  - #to_a: Returns a new array of 2-element arrays;
  *    each nested array contains a key-value pair from +self+.
@@ -7174,15 +7179,13 @@ static const rb_data_type_t env_data_type = {
  *
  *  ==== Methods for Transforming Keys and Values
  *
+ *  - #flatten!: Returns +self+, flattened.
+ *  - #invert: Returns a hash with the each key-value pair inverted.
  *  - #transform_keys: Returns a copy of +self+ with modified keys.
  *  - #transform_keys!: Modifies keys in +self+
  *  - #transform_values: Returns a copy of +self+ with modified values.
  *  - #transform_values!: Modifies values in +self+.
  *
- *  ==== Other Methods
- *  - #flatten: Returns an array that is a 1-dimensional flattening of +self+.
- *  - #invert: Returns a hash with the each key-value pair inverted.
- *
  */
 
 void