From 0960c8aacd30c28347de6b7d906df0c5d2d86b41 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Thu, 12 Sep 2024 14:19:20 -0500
Subject: [PATCH] [DOC] Tweaks for Array#fetch_values (#11603)

---
 array.c  |  1 +
 array.rb | 35 +++++++++++++++++++++++++----------
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/array.c b/array.c
index 059d6911ee..fcfe01ab87 100644
--- a/array.c
+++ b/array.c
@@ -8600,6 +8600,7 @@ rb_ary_deconstruct(VALUE ary)
  *
  *  - #[] (aliased as #slice): Returns consecutive elements as determined by a given argument.
  *  - #fetch: Returns the element at a given offset.
+ *  - #fetch_values: Returns elements at given offsets.
  *  - #first: Returns one or more leading elements.
  *  - #last: Returns one or more trailing elements.
  *  - #max: Returns one or more maximum-valued elements,
diff --git a/array.rb b/array.rb
index 4b4c2c0ac8..7450322336 100644
--- a/array.rb
+++ b/array.rb
@@ -201,22 +201,37 @@ class Array
   end
 
   #  call-seq:
-  #    array.fetch_values(*indexes) -> new_array
-  #    array.fetch_values(*indexes) {|key| ... } -> new_array
+  #    fetch_values(*indexes) -> new_array
+  #    fetch_values(*indexes) {|index| ... } -> new_array
+  #
+  #  With no block given, returns a new array containing the elements of +self+
+  #  at the offsets given by +indexes+;
+  #  each of the +indexes+ must be an
+  #  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]:
   #
-  #  Returns a new Array containing the values associated with the given indexes *indexes:
   #    a = [:foo, :bar, :baz]
-  #    a.fetch_values(3, 1) # => [:baz, :foo]
+  #    a.fetch_values(3, 1)   # => [:baz, :foo]
+  #    a.fetch_values(3.1, 1) # => [:baz, :foo]
+  #    a.fetch_values         # => []
   #
-  #  Returns a new empty Array if no arguments given.
+  #  For a negative index, counts backwards from the end of the array:
+  #
+  #    a.fetch_values([-2, -1]) # [:bar, :baz]
+  #
+  #  When no block is given, raises an exception if any index is out of range.
+  #
+  #  With a block given, for each index:
+  #
+  #  - If the index in in range, uses an element of +self+ (as above).
+  #  - Otherwise calls, the block with the index, and uses the block's return value.
+  #
+  #  Example:
   #
-  #  When a block is given, calls the block with each missing index,
-  #  treating the block's return value as the value for that index:
   #    a = [:foo, :bar, :baz]
-  #    values = a.fetch_values(1, 0, 42, 777) {|index| index.to_s}
-  #    values # => [:bar, :foo, "42", "777"]
+  #    a.fetch_values(1, 0, 42, 777) {|index| index.to_s}
+  #    # => [:bar, :foo, "42", "777"]
   #
-  #  When no block is given, raises an exception if any given key is not found.
+  #  Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
   def fetch_values(*indexes, &block)
     indexes.map! { |i| fetch(i, &block) }
     indexes