[DOC] Adjust some new features wording/examples. (#9183)

* Reword Range#overlap? docs last paragraph.

* Docs: add explanation about Queue#freeze

* Docs: Add :rescue event docs for TracePoint

* Docs: Enhance Module#set_temporary_name documentation

* Docs: Slightly expand Process::Status deprecations

* Fix MatchData#named_captures rendering glitch

* Improve Dir.fchdir examples

* Adjust Refinement#target docs

dir.c

@@ -1254,10 +1254,8 @@ fchdir_restore(VALUE v)
  *   Dir.pwd # => "/var/spool/mail"
  *   dir  = Dir.new('/usr')
  *   fd = dir.fileno
- *   Dir.fchdir(fd) do
+ *   Dir.fchdir(fd)
  *   Dir.pwd # => "/usr"
- *   end
- *   Dir.pwd # => "/var/spool/mail"
  *
  * With a block, temporarily changes the working directory:
  *
@@ -1271,7 +1269,9 @@ fchdir_restore(VALUE v)
  *
  *   Dir.chdir('/var/spool/mail')
  *   Dir.pwd # => "/var/spool/mail"
- *   Dir.chdir('/tmp') do
+ *   dir  = Dir.new('/tmp')
+ *   fd = dir.fileno
+ *   Dir.fchdir(fd) do
  *     Dir.pwd # => "/tmp"
  *   end
  *   Dir.pwd # => "/var/spool/mail"

eval.c

@@ -1346,9 +1346,16 @@ rb_using_module(const rb_cref_t *cref, VALUE module)
 
 /*
  *  call-seq:
- *     target    -> class
+ *     target    -> class_or_module
  *
  *  Return the class or module refined by the receiver.
+ *
+ *     module M
+ *       refine String do
+ *       end
+ *     end
+ *
+ *     M.refinements[0].target # => String
  */
 VALUE
 rb_refinement_module_get_refined_class(VALUE module)
@@ -1363,6 +1370,8 @@ rb_refinement_module_get_refined_class(VALUE module)
  *  call-seq:
  *     refined_class    -> class
  *
+ *  Deprecated; prefer #target.
+ *
  *  Return the class refined by the receiver.
  */
 static VALUE

process.c

@@ -576,7 +576,6 @@ proc_get_ppid(VALUE _)
  *    stat = $?       # => #<Process::Status: pid 1262862 exit 99>
  *    stat.class      # => Process::Status
  *    stat.to_i       # => 25344
- *    stat >> 8       # => 99
  *    stat.stopped?   # => false
  *    stat.exited?    # => true
  *    stat.exitstatus # => 99
@@ -878,7 +877,9 @@ pst_equal(VALUE st1, VALUE st2)
  *  call-seq:
  *    stat & mask -> integer
  *
- *  This method is deprecated; use other attribute methods.
+ *  This method is deprecated as #to_i value is system-specific; use
+ *  predicate methods like #exited? or #stopped?, or getters like #exitstatus
+ *  or #stopsig.
  *
  *  Returns the logical AND of the value of #to_i with +mask+:
  *
@@ -930,7 +931,9 @@ pst_bitand(VALUE st1, VALUE st2)
  *  call-seq:
  *    stat >> places -> integer
  *
- *  This method is deprecated; use other predicate methods.
+ *  This method is deprecated as #to_i value is system-specific; use
+ *  predicate methods like #exited? or #stopped?, or getters like #exitstatus
+ *  or #stopsig.
  *
  *  Returns the value of #to_i, shifted +places+ to the right:
  *

range.c

@@ -2391,18 +2391,17 @@ empty_region_p(VALUE beg, VALUE end, int excl)
  *    (1..2).overlap?(3..4)      # => false
  *    (1...3).overlap?(3..4)     # => false
  *
- *  This method assumes that there is no minimum value because
+ *  Note that the method wouldn't make any assumptions about the beginless
- *  Ruby lacks a standard method for determining minimum values.
+ *  range being actually empty, even if its upper bound is the minimum
- *  This assumption is invalid.
+ *  possible value of its type, so all this would return +true+:
- *  For example, there is no value smaller than <tt>-Float::INFINITY</tt>,
+ *
- *  making <tt>(...-Float::INFINITY)</tt> an empty set.
+ *     (...-Float::INFINITY).overlap?(...-Float::INFINITY) # => true
- *  Consequently, <tt>(...-Float::INFINITY)</tt> has no elements in common with itself,
+ *     (..."").overlap?(..."") # => true
- *  yet <tt>(...-Float::INFINITY).overlap?((...-Float::INFINITY))<tt> returns
+ *     (...[]).overlap?(...[]) # => true
- *  +true+ due to this assumption.
+ *
- *  In general, if <tt>r = (...minimum); r.overlap?(r)</tt> returns +true+,
+ *  Even if those ranges are effectively empty (no number can be smaller than
- *  where +minimum+ is a value that no value is smaller than.
+ *  <tt>-Float::INFINITY</tt>), they are still considered overlapping
- *  Such values include <tt>-Float::INFINITY</tt>, <tt>[]</tt>, <tt>""</tt>, and
+ *  with themselves.
- *  classes without subclasses.
  *
  *  Related: Range#cover?.
  */

thread_sync.c

@@ -1163,8 +1163,9 @@ NORETURN(static VALUE rb_queue_freeze(VALUE self));
  * call-seq:
  *   freeze
  *
- * Raises an exception:
+ * The queue can't be frozen, so this method raises an exception:
- *   Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+ *   Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+ *
  */
 static VALUE
 rb_queue_freeze(VALUE self)

trace_point.rb

@@ -37,6 +37,7 @@
 # +:c_call+:: call a C-language routine
 # +:c_return+:: return from a C-language routine
 # +:raise+:: raise an exception
+# +:rescue+:: rescue an exception
 # +:b_call+:: event hook at block entry
 # +:b_return+:: event hook at block ending
 # +:a_call+:: event hook at all calls (+call+, +b_call+, and +c_call+)
@@ -375,7 +376,7 @@ class TracePoint
 
   # Return the generated binding object from event.
   #
-  # Note that for +c_call+ and +c_return+ events, the method will return
+  # Note that for +:c_call+ and +:c_return+ events, the method will return
   # +nil+, since C methods themselves do not have bindings.
   def binding
     Primitive.tracepoint_attr_binding
@@ -384,19 +385,19 @@ class TracePoint
   # Return the trace object during event
   #
   # Same as the following, except it returns the correct object (the method
-  # receiver) for +c_call+ and +c_return+ events:
+  # receiver) for +:c_call+ and +:c_return+ events:
   #
   #   trace.binding.eval('self')
   def self
     Primitive.tracepoint_attr_self
   end
 
-  #  Return value from +:return+, +c_return+, and +b_return+ event
+  #  Return value from +:return+, +:c_return+, and +:b_return+ event
   def return_value
     Primitive.tracepoint_attr_return_value
   end
 
-  # Value from exception raised on the +:raise+ event
+  # Value from exception raised on the +:raise+ event, or rescued on the +:rescue+ event.
   def raised_exception
     Primitive.tracepoint_attr_raised_exception
   end

variable.c

@@ -162,21 +162,21 @@ is_constant_path(VALUE name)
  *     mod.set_temporary_name(string) -> self
  *     mod.set_temporary_name(nil) -> self
  *
- *  Sets the temporary name of the module +mod+. This name is used as a prefix
+ *  Sets the temporary name of the module. This name is reflected in
- *  for the names of constants declared in +mod+. If the module is assigned a
+ *  introspection of the module and the values that are related to it, such
- *  permanent name, the temporary name is discarded.
+ *  as instances, constants, and methods.
  *
- *  After a permanent name is assigned, a temporary name can no longer be set,
+ *  The name should be +nil+ or non-empty string that is not a valid constant
- *  and this method raises a RuntimeError.
+ *  name (to avoid confusing between permanent and temporary names).
  *
- *  If the name given is not a string or is a zero length string, this method
+ *  The method can be useful to distinguish dynamically generated classes and
- *  raises an ArgumentError.
+ *  modules without assigning them to constants.
  *
- *  The temporary name must not be a valid constant name, to avoid confusion
+ *  If the module is given a permanent name by assigning it to a constant,
- *  with actual constants. If you attempt to set a temporary name that is a
+ *  the temporary name is discarded. A temporary name can't be assigned to
- *  a valid constant name, this method raises an ArgumentError.
+ *  modules that have a permanent name.
  *
- *  If the given name is +nil+, the module becomes anonymous.
+ *  If the given name is +nil+, the module becomes anonymous again.
  *
  *  Example:
  *
@@ -189,15 +189,20 @@ is_constant_path(VALUE name)
  *    m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
  *    m.name #=> nil
  *
- *    n = Module.new
+ *    c = Class.new
- *    n.set_temporary_name("fake_name")
+ *    c.set_temporary_name("MyClass(with description)")
  *
- *    n::M = m
+ *    c.new # => #<MyClass(with description):0x0....>
- *    n::M.name #=> "fake_name::M"
- *    N = n
  *
- *    N.name #=> "N"
+ *    c::M = m
- *    N::M.name #=> "N::M"
+ *    c::M.name #=> "MyClass(with description)::M"
+ *
+ *    # Assigning to a constant replaces the name with a permanent one
+ *    C = c
+ *
+ *    C.name #=> "C"
+ *    C::M.name #=> "C::M"
+ *    c.new # => #<C:0x0....>
  */
 
 VALUE