Small documentation adjustments for new/updated features (#15634)

* Document Range#to_set

* Update Thread#raise and Fiber#raise signatures and docs

* Add reference to String#strip to character_selectors.rdoc

* Update *nil docs when calling methods

* Enhance Array#find and #rfind docs

* Add a notice to Kernel#raise about cause:

Author: zverok

array.c

@@ -2102,9 +2102,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  *
  * If no such element is found, calls +if_none_proc+ and returns its return value.
  *
- *   [1, 3, 5].find(proc {false}) {|element| element > 12} # => false
- *   [[:foo, 0], [:bar, 1], [:baz, 2]].find {|key, value| key.start_with?('b') }            # => [:bar, 1]
- *   [[:foo, 0], [:bar, 1], [:baz, 2]].find(proc {[]}) {|key, value| key.start_with?('c') } # => []
+ *   [1, 3, 5].find(proc {-1}) {|element| element > 12} # => -1
  *
  * With no block given, returns an Enumerator.
  *
@@ -2140,16 +2138,14 @@ rb_ary_find(int argc, VALUE *argv, VALUE ary)
  * Returns the last element for which the block returns a truthy value.
  *
  * With a block given, calls the block with successive elements of the array in
- * reverse order; returns the last element for which the block returns a truthy
+ * reverse order; returns the first element for which the block returns a truthy
  * value:
  *
- *   (0..9).rfind {|element| element < 5}                # => 4
+ *   [1, 2, 3, 4, 5, 6].rfind {|element| element < 5}       # => 4
  *
  * If no such element is found, calls +if_none_proc+ and returns its return value.
  *
- *   (0..9).rfind(proc {false}) {|element| element < -2} # => false
- *   {foo: 0, bar: 1, baz: 2}.rfind {|key, value| key.start_with?('b') }            # => [:baz, 2]
- *   {foo: 0, bar: 1, baz: 2}.rfind(proc {[]}) {|key, value| key.start_with?('c') } # => []
+ *   [1, 2, 3, 4].rfind(proc {0}) {|element| element < -2}  # => 0
  *
  * With no block given, returns an Enumerator.
  *

cont.c

@@ -3246,28 +3246,37 @@ rb_fiber_raise(VALUE fiber, int argc, VALUE *argv)
 
 /*
  *  call-seq:
- *     fiber.raise                                 -> obj
- *     fiber.raise(string)                         -> obj
- *     fiber.raise(exception [, string [, array]]) -> obj
+ *    raise(exception, message = exception.to_s, backtrace = nil, cause: $!)
+ *    raise(message = nil, cause: $!)
  *
  *  Raises an exception in the fiber at the point at which the last
- *  +Fiber.yield+ was called. If the fiber has not been started or has
+ *  +Fiber.yield+ was called.
+ *
+ *     f = Fiber.new {
+ *       puts "Before the yield"
+ *       Fiber.yield 1 # -- exception will be raised here
+ *       puts "After the yield"
+ *     }
+ *
+ *     p f.resume
+ *     f.raise "Gotcha"
+ *
+ *  Output
+ *
+ *     Before the first yield
+ *     1
+ *     t.rb:8:in 'Fiber.yield': Gotcha (RuntimeError)
+ *       from t.rb:8:in 'block in <main>'
+ *
+ *  If the fiber has not been started or has
  *  already run to completion, raises +FiberError+. If the fiber is
  *  yielding, it is resumed. If it is transferring, it is transferred into.
  *  But if it is resuming, raises +FiberError+.
  *
- *  With no arguments, raises a +RuntimeError+. With a single +String+
- *  argument, raises a +RuntimeError+ with the string as a message.  Otherwise,
- *  the first parameter should be the name of an +Exception+ class (or an
- *  object that returns an +Exception+ object when sent an +exception+
- *  message). The optional second parameter sets the message associated with
- *  the exception, and the third parameter is an array of callback information.
- *  Exceptions are caught by the +rescue+ clause of <code>begin...end</code>
- *  blocks.
- *
  *  Raises +FiberError+ if called on a Fiber belonging to another +Thread+.
  *
- *  See Kernel#raise for more information.
+ *  See Kernel#raise for more information on arguments.
+ *
  */
 static VALUE
 rb_fiber_m_raise(int argc, VALUE *argv, VALUE self)

doc/language/character_selectors.rdoc

@@ -14,6 +14,8 @@ Each of these instance methods accepts one or more character selectors:
 - String#delete!(*selectors): returns +self+ or +nil+.
 - String#squeeze(*selectors): returns a new string.
 - String#squeeze!(*selectors): returns +self+ or +nil+.
+- String#strip(*selectors): returns a new string.
+- String#strip!(*selectors): returns +self+ or +nil+.
 
 A character selector identifies zero or more characters in +self+
 that are to be operands for the method.
@@ -79,6 +81,8 @@ These instance methods accept multiple character selectors:
 - String#delete!(*selectors): returns +self+ or +nil+.
 - String#squeeze(*selectors): returns a new string.
 - String#squeeze!(*selectors): returns +self+ or +nil+.
+- String#strip(*selectors): returns a new string.
+- String#strip!(*selectors): returns +self+ or +nil+.
 
 In effect, the given selectors are formed into a single selector
 consisting of only those characters common to _all_ of the given selectors.

doc/syntax/calling_methods.rdoc

@@ -355,9 +355,8 @@ as one argument:
   # Prints the object itself:
   #   #<Name:0x00007f9d07bca650 @name="Jane Doe">
 
-This allows to handle one or many arguments polymorphically. Note also that +nil+
-has NilClass#to_a defined to return an empty array, so conditional unpacking is
-possible:
+This allows to handle one or many arguments polymorphically. Note also that <tt>*nil</tt>
+is unpacked to an empty list of arguments, so conditional unpacking is possible:
 
   my_method(*(some_arguments if some_condition?))
 

eval.c

@@ -922,6 +922,9 @@ rb_f_raise(int argc, VALUE *argv)
  *  With argument +exception+ not given,
  *  argument +message+ and keyword argument +cause+ may be given,
  *  but argument +backtrace+ may not be given.
+ *
+ *  +cause+ can not be given as an only argument.
+ *
  */
 
 static VALUE

range.c

@@ -1018,6 +1018,20 @@ range_to_a(VALUE range)
     return rb_call_super(0, 0);
 }
 
+/*
+ *  call-seq:
+ *    to_set -> set
+ *
+ *  Returns a set containing the elements in +self+, if a finite collection;
+ *  raises an exception otherwise.
+ *
+ *    (1..4).to_set   # => Set[1, 2, 3, 4]
+ *    (1...4).to_set   # => Set[1, 2, 3]
+ *
+ *    (1..).to_set
+ *    # in 'Range#to_set': cannot convert endless range to a set (RangeError)
+ *
+ */
 static VALUE
 range_to_set(int argc, VALUE *argv, VALUE range)
 {

thread.c

@@ -2908,12 +2908,11 @@ rb_thread_fd_close(int fd)
 
 /*
  *  call-seq:
- *     thr.raise
- *     thr.raise(string)
- *     thr.raise(exception [, string [, array]])
+ *    raise(exception, message = exception.to_s, backtrace = nil, cause: $!)
+ *    raise(message = nil, cause: $!)
  *
  *  Raises an exception from the given thread. The caller does not have to be
- *  +thr+. See Kernel#raise for more information.
+ *  +thr+. See Kernel#raise for more information on arguments.
  *
  *     Thread.abort_on_exception = true
  *     a = Thread.new { sleep(200) }