From 54274b8c65a0981f1c69055a1513ba3c614dd675 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Wed, 6 Sep 2023 17:26:11 -0500
Subject: [PATCH] [DOC] Rdoc for Process::Status (#8386)

---
 process.c | 89 ++++++++++++++++++++++++++-----------------------------
 1 file changed, 42 insertions(+), 47 deletions(-)

diff --git a/process.c b/process.c
index acb74c2d47b167..aaea02a0f808c6 100644
--- a/process.c
+++ b/process.c
@@ -857,10 +857,15 @@ pst_inspect(VALUE st)
 
 /*
  *  call-seq:
- *     stat == other   -> true or false
+ *    stat == other -> true or false
+ *
+ *  Returns whether the value of #to_i == +other+:
+ *
+ *    `cat /nop`
+ *    stat = $?                # => #<Process::Status: pid 1170366 exit 1>
+ *    sprintf('%x', stat.to_i) # => "100"
+ *    stat == 0x100            # => true
  *
- *  Returns +true+ if the integer value of _stat_
- *  equals <em>other</em>.
  */
 
 static VALUE
@@ -873,14 +878,15 @@ pst_equal(VALUE st1, VALUE st2)
 
 /*
  *  call-seq:
- *     stat & num   -> integer
+ *    stat & mask -> integer
+ *
+ *  Returns the logical AND of the value of #to_i with +mask+:
  *
- *  Logical AND of the bits in _stat_ with <em>num</em>.
+ *    `cat /nop`
+ *    stat = $?                 # => #<Process::Status: pid 1155508 exit 1>
+ *    sprintf('%x', stat.to_i)  # => "100"
+ *    stat & 0x00               # => 0
  *
- *     fork { exit 0x37 }
- *     Process.wait
- *     sprintf('%04x', $?.to_i)       #=> "3700"
- *     sprintf('%04x', $? & 0x1e00)   #=> "1600"
  */
 
 static VALUE
@@ -894,14 +900,17 @@ pst_bitand(VALUE st1, VALUE st2)
 
 /*
  *  call-seq:
- *     stat >> num   -> integer
+ *    stat >> places -> integer
  *
- *  Shift the bits in _stat_ right <em>num</em> places.
+ *  Returns the value of #to_i, shifted +places+ to the right:
  *
- *     fork { exit 99 }   #=> 26563
- *     Process.wait       #=> 26563
- *     $?.to_i            #=> 25344
- *     $? >> 8            #=> 99
+ *     `cat /nop`
+ *     stat = $?                 # => #<Process::Status: pid 1155508 exit 1>
+ *     stat.to_i                 # => 256
+ *     stat >> 1                 # => 128
+ *     stat >> 2                 # => 64
+ *
+ *  Returns zero if +places+ is negative.
  */
 
 static VALUE
@@ -1155,46 +1164,32 @@ rb_process_status_wait(rb_pid_t pid, int flags)
 
 /*
  *  call-seq:
- *     Process::Status.wait(pid=-1, flags=0)      -> Process::Status
+ *     Process::Status.wait(pid = -1, flags = 0) -> Process::Status
  *
- *  Waits for a child process to exit and returns a Process::Status object
- *  containing information on that process. Which child it waits on
- *  depends on the value of _pid_:
+ *  Like Process.wait, but returns a Process::Status object
+ *  (instead of an integer pid or nil);
+ *  see Process.wait for the values of +pid+ and +flags+.
  *
- *  > 0::   Waits for the child whose process ID equals _pid_.
+ *  If there are child processes,
+ *  waits for a child process to exit and returns a Process::Status object
+ *  containing information on that process;
+ *  sets thread-local variable <tt>$?</tt>:
  *
- *  0::     Waits for any child whose process group ID equals that of the
- *          calling process.
+ *    Process.spawn('cat /nop') # => 1155880
+ *    Process::Status.wait      # => #<Process::Status: pid 1155880 exit 1>
+ *    $?                        # => #<Process::Status: pid 1155508 exit 1>
  *
- *  -1::    Waits for any child process (the default if no _pid_ is
- *          given).
+ *  If there is no child process,
+ *  returns an "empty" Process::Status object
+ *  that does not represent an actual process;
+ *  does not set thread-local variable <tt>$?</tt>:
  *
- *  < -1::  Waits for any child whose process group ID equals the absolute
- *          value of _pid_.
+ *    Process::Status.wait # => #<Process::Status: pid -1 exit 0>
+ *    $?                   # => #<Process::Status: pid 1155508 exit 1> # Unchanged.
  *
- *  The _flags_ argument may be a logical or of the flag values
- *  Process::WNOHANG (do not block if no child available)
- *  or Process::WUNTRACED (return stopped children that
- *  haven't been reported). Not all flags are available on all
- *  platforms, but a flag value of zero will work on all platforms.
+ *  May invoke the scheduler hook Fiber::Scheduler#process_wait.
  *
- *  Returns +nil+ if there are no child processes.
  *  Not available on all platforms.
- *
- *  May invoke the scheduler hook _process_wait_.
- *
- *     fork { exit 99 }                              #=> 27429
- *     Process::Status.wait                          #=> pid 27429 exit 99
- *     $?                                            #=> nil
- *
- *     pid = fork { sleep 3 }                        #=> 27440
- *     Time.now                                      #=> 2008-03-08 19:56:16 +0900
- *     Process::Status.wait(pid, Process::WNOHANG)   #=> nil
- *     Time.now                                      #=> 2008-03-08 19:56:16 +0900
- *     Process::Status.wait(pid, 0)                  #=> pid 27440 exit 99
- *     Time.now                                      #=> 2008-03-08 19:56:19 +0900
- *
- *  This is an EXPERIMENTAL FEATURE.
  */
 
 static VALUE