Update set_backtrace documentation

Followup: https://github.com/ruby/ruby/pull/10017

[Feature #13557]

NEWS.md

@@ -22,6 +22,11 @@ Note that each entry is kept to a minimum, see links for details.
 
 Note: We're only listing outstanding class updates.
 
+* Exception
+
+  * Exception#set_backtrace now accepts arrays of `Thread::Backtrace::Location`.
+    `Kernel#raise`, `Thread#raise` and `Fiber#raise` also accept this new format. [Feature #13557]
+
 ## Stdlib updates
 
 The following default gems are updated.

cont.c

@@ -3268,6 +3268,8 @@ rb_fiber_raise(VALUE fiber, int argc, const VALUE *argv)
  *  blocks.
  *
  *  Raises +FiberError+ if called on a Fiber belonging to another +Thread+.
+ *
+ *  See Kernel#raise for more information.
  */
 static VALUE
 rb_fiber_m_raise(int argc, VALUE *argv, VALUE self)

error.c

@@ -1862,8 +1862,8 @@ rb_check_backtrace(VALUE bt)
  *     exc.set_backtrace(backtrace)   ->  array
  *
  *  Sets the backtrace information associated with +exc+. The +backtrace+ must
- *  be an array of String objects or a single String in the format described
+ *  be an array of Thread::Backtrace::Location objects or an array of String objects
- *  in Exception#backtrace.
+ *  or a single String in the format described in Exception#backtrace.
  *
  */
 

eval.c

@@ -761,7 +761,8 @@ rb_f_raise(int argc, VALUE *argv)
  *  object that returns an +Exception+ object when sent an +exception+
  *  message).  The optional second parameter sets the message associated with
  *  the exception (accessible via Exception#message), and the third parameter
- *  is an array of callback information (accessible via Exception#backtrace).
+ *  is an array of callback information (accessible via
+ *  Exception#backtrace_locations or Exception#backtrace).
  *  The +cause+ of the generated exception (accessible via Exception#cause)
  *  is automatically set to the "current" exception (<code>$!</code>), if any.
  *  An alternative value, either an +Exception+ object or +nil+, can be
@@ -771,7 +772,7 @@ rb_f_raise(int argc, VALUE *argv)
  *  <code>begin...end</code> blocks.
  *
  *     raise "Failed to create socket"
- *     raise ArgumentError, "No parameters", caller
+ *     raise ArgumentError, "No parameters", caller_locations
  */
 
 static VALUE

spec/ruby/shared/kernel/raise.rb

@@ -148,10 +148,13 @@ describe :kernel_raise, shared: true do
   end
 
   ruby_version_is "3.4" do
+    locations = caller_locations(1, 2)
     it "allows Exception, message, and backtrace_locations parameters" do
       -> do
-        @object.raise(ArgumentError, "message", caller_locations)
+        @object.raise(ArgumentError, "message", locations)
-      end.should raise_error(ArgumentError, "message")
+      end.should raise_error(ArgumentError, "message") { |error|
+        error.backtrace_locations.map(&:to_s).should == locations.map(&:to_s)
+      }
     end
   end
 end