rbs 2.8.4 → 3.8.1

data/core/process.rbs

@@ -1,18 +1,403 @@
 # <!-- rdoc-file=process.c -->
-# The module contains several groups of functionality for handling OS processes:
-#
-# *   Low-level property introspection and management of the current process,
-#     like Process.argv0, Process.pid;
-# *   Low-level introspection of other processes, like Process.getpgid,
-#     Process.getpriority;
-# *   Management of the current process: Process.abort, Process.exit,
-#     Process.daemon, etc. (for convenience, most of those are also available as
-#     global functions and module functions of Kernel);
-# *   Creation and management of child processes: Process.fork, Process.spawn,
-#     and related methods;
-# *   Management of low-level system clock: Process.times and
-#     Process.clock_gettime, which could be important for proper benchmarking
-#     and other elapsed time measurement tasks.
+# Module `Process` represents a process in the underlying operating system. Its
+# methods support management of the current process and its child processes.
+#
+# ## Process Creation
+#
+# Each of the following methods executes a given command in a new process or
+# subshell, or multiple commands in new processes and/or subshells. The choice
+# of process or subshell depends on the form of the command; see [Argument
+# command_line or exe_path](rdoc-ref:Process@Argument+command_line+or+exe_path).
+#
+# *   Process.spawn, Kernel#spawn: Executes the command; returns the new pid
+#     without waiting for completion.
+# *   Process.exec: Replaces the current process by executing the command.
+#
+# In addition:
+#
+# *   Method Kernel#system executes a given command-line (string) in a subshell;
+#     returns `true`, `false`, or `nil`.
+# *   Method Kernel#` executes a given command-line (string) in a subshell;
+#     returns its $stdout string.
+# *   Module Open3 supports creating child processes with access to their
+#     $stdin, $stdout, and $stderr streams.
+#
+# ### Execution Environment
+#
+# Optional leading argument `env` is a hash of name/value pairs, where each name
+# is a string and each value is a string or `nil`; each name/value pair is added
+# to ENV in the new process.
+#
+#     Process.spawn(                'ruby -e "p ENV[\"Foo\"]"')
+#     Process.spawn({'Foo' => '0'}, 'ruby -e "p ENV[\"Foo\"]"')
+#
+# Output:
+#
+#     "0"
+#
+# The effect is usually similar to that of calling ENV#update with argument
+# `env`, where each named environment variable is created or updated (if the
+# value is non-`nil`), or deleted (if the value is `nil`).
+#
+# However, some modifications to the calling process may remain if the new
+# process fails. For example, hard resource limits are not restored.
+#
+# ### Argument `command_line` or `exe_path`
+#
+# The required string argument is one of the following:
+#
+# *   `command_line` if it begins with a shell reserved word or special
+#     built-in, or if it contains one or more meta characters.
+# *   `exe_path` otherwise.
+#
+# #### Argument `command_line`
+#
+# String argument `command_line` is a command line to be passed to a shell; it
+# must begin with a shell reserved word, begin with a special built-in, or
+# contain meta characters:
+#
+#     system('if true; then echo "Foo"; fi')          # => true  # Shell reserved word.
+#     system('exit')                                  # => true  # Built-in.
+#     system('date > /tmp/date.tmp')                  # => true  # Contains meta character.
+#     system('date > /nop/date.tmp')                  # => false
+#     system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.
+#
+# The command line may also contain arguments and options for the command:
+#
+#     system('echo "Foo"') # => true
+#
+# Output:
+#
+#     Foo
+#
+# See [Execution Shell](rdoc-ref:Process@Execution+Shell) for details about the
+# shell.
+#
+# #### Argument `exe_path`
+#
+# Argument `exe_path` is one of the following:
+#
+# *   The string path to an executable file to be called:
+#
+#     Example:
+#
+#         system('/usr/bin/date') # => true # Path to date on Unix-style system.
+#         system('foo')           # => nil  # Command execlution failed.
+#
+#     Output:
+#
+#         Thu Aug 31 10:06:48 AM CDT 2023
+#
+#     A path or command name containing spaces without arguments cannot be
+#     distinguished from `command_line` above, so you must quote or escape the
+#     entire command name using a shell in platform dependent manner, or use the
+#     array form below.
+#
+#     If `exe_path` does not contain any path separator, an executable file is
+#     searched from directories specified with the `PATH` environment variable.
+#     What the word "executable" means here is depending on platforms.
+#
+#     Even if the file considered "executable", its content may not be in proper
+#     executable format.  In that case, Ruby tries to run it by using `/bin/sh`
+#     on a Unix-like system, like system(3) does.
+#
+#         File.write('shell_command', 'echo $SHELL', perm: 0o755)
+#         system('./shell_command')        # prints "/bin/sh" or something.
+#
+# *   A 2-element array containing the path to an executable and the string to
+#     be used as the name of the executing process:
+#
+#     Example:
+#
+#         pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
+#         p `ps -p #{pid} -o command=`
+#
+#     Output:
+#
+#         "Hello! 1\n"
+#
+# ### Arguments `args`
+#
+# If `command_line` does not contain shell meta characters except for spaces and
+# tabs, or `exe_path` is given, Ruby invokes the executable directly.  This form
+# does not use the shell:
+#
+#     spawn("doesnt_exist")       # Raises Errno::ENOENT
+#     spawn("doesnt_exist", "\n") # Raises Errno::ENOENT
+#
+#     spawn("doesnt_exist\n")     # => false
+#     # sh: 1: doesnot_exist: not found
+#
+# The error message is from a shell and would vary depending on your system.
+#
+# If one or more `args` is given after `exe_path`, each is an argument or option
+# to be passed to the executable:
+#
+# Example:
+#
+#     system('echo', '<', 'C*', '|', '$SHELL', '>')   # => true
+#
+# Output:
+#
+#     < C* | $SHELL >
+#
+# However, there are exceptions on Windows.  See [Execution Shell on
+# Windows](rdoc-ref:Process@Execution+Shell+on+Windows).
+#
+# If you want to invoke a path containing spaces with no arguments without
+# shell, you will need to use a 2-element array `exe_path`.
+#
+# Example:
+#
+#     path = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+#     spawn(path) # Raises Errno::ENOENT; No such file or directory - /Applications/Google
+#     spawn([path] * 2)
+#
+# ### Execution Options
+#
+# Optional trailing argument `options` is a hash of execution options.
+#
+# #### Working Directory (`:chdir`)
+#
+# By default, the working directory for the new process is the same as that of
+# the current process:
+#
+#     Dir.chdir('/var')
+#     Process.spawn('ruby -e "puts Dir.pwd"')
+#
+# Output:
+#
+#     /var
+#
+# Use option `:chdir` to set the working directory for the new process:
+#
+#     Process.spawn('ruby -e "puts Dir.pwd"', {chdir: '/tmp'})
+#
+# Output:
+#
+#     /tmp
+#
+# The working directory of the current process is not changed:
+#
+#     Dir.pwd # => "/var"
+#
+# #### File Redirection (File Descriptor)
+#
+# Use execution options for file redirection in the new process.
+#
+# The key for such an option may be an integer file descriptor (fd), specifying
+# a source, or an array of fds, specifying multiple sources.
+#
+# An integer source fd may be specified as:
+#
+# *   *n*: Specifies file descriptor *n*.
+#
+# There are these shorthand symbols for fds:
+#
+# *   `:in`: Specifies file descriptor 0 (STDIN).
+# *   `:out`: Specifies file descriptor 1 (STDOUT).
+# *   `:err`: Specifies file descriptor 2 (STDERR).
+#
+# The value given with a source is one of:
+#
+# *   *n*: Redirects to fd *n* in the parent process.
+# *   `filepath`: Redirects from or to the file at `filepath` via
+#     `open(filepath, mode, 0644)`, where `mode` is `'r'` for source `:in`, or
+#     `'w'` for source `:out` or `:err`.
+# *   `[filepath]`: Redirects from the file at `filepath` via `open(filepath,
+#     'r', 0644)`.
+# *   `[filepath, mode]`: Redirects from or to the file at `filepath` via
+#     `open(filepath, mode, 0644)`.
+# *   `[filepath, mode, perm]`: Redirects from or to the file at `filepath` via
+#     `open(filepath, mode, perm)`.
+# *   `[:child, fd]`: Redirects to the redirected `fd`.
+# *   `:close`: Closes the file descriptor in child process.
+#
+# See [Access Modes](rdoc-ref:File@Access+Modes) and [File
+# Permissions](rdoc-ref:File@File+Permissions).
+#
+# #### Environment Variables (`:unsetenv_others`)
+#
+# By default, the new process inherits environment variables from the parent
+# process; use execution option key `:unsetenv_others` with value `true` to
+# clear environment variables in the new process.
+#
+# Any changes specified by execution option `env` are made after the new process
+# inherits or clears its environment variables; see [Execution
+# Environment](rdoc-ref:Process@Execution+Environment).
+#
+# #### File-Creation Access (`:umask`)
+#
+# Use execution option `:umask` to set the file-creation access for the new
+# process; see [Access Modes](rdoc-ref:File@Access+Modes):
+#
+#     command = 'ruby -e "puts sprintf(\"0%o\", File.umask)"'
+#     options = {:umask => 0644}
+#     Process.spawn(command, options)
+#
+# Output:
+#
+#     0644
+#
+# #### Process Groups (`:pgroup` and `:new_pgroup`)
+#
+# By default, the new process belongs to the same [process
+# group](https://en.wikipedia.org/wiki/Process_group) as the parent process.
+#
+# To specify a different process group. use execution option `:pgroup` with one
+# of the following values:
+#
+# *   `true`: Create a new process group for the new process.
+# *   *pgid*: Create the new process in the process group whose id is *pgid*.
+#
+# On Windows only, use execution option `:new_pgroup` with value `true` to
+# create a new process group for the new process.
+#
+# #### Resource Limits
+#
+# Use execution options to set resource limits.
+#
+# The keys for these options are symbols of the form `:rlimit_*resource_name`*,
+# where *resource_name* is the downcased form of one of the string resource
+# names described at method Process.setrlimit. For example, key `:rlimit_cpu`
+# corresponds to resource limit `'CPU'`.
+#
+# The value for such as key is one of:
+#
+# *   An integer, specifying both the current and maximum limits.
+# *   A 2-element array of integers, specifying the current and maximum limits.
+#
+# #### File Descriptor Inheritance
+#
+# By default, the new process inherits file descriptors from the parent process.
+#
+# Use execution option `:close_others => true` to modify that inheritance by
+# closing non-standard fds (3 and greater) that are not otherwise redirected.
+#
+# ### Execution Shell
+#
+# On a Unix-like system, the shell invoked is `/bin/sh`; the entire string
+# `command_line` is passed as an argument to [shell option
+# -c](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/utilities/sh.
+# html).
+#
+# The shell performs normal shell expansion on the command line:
+#
+# Example:
+#
+#     system('echo $SHELL: C*') # => true
+#
+# Output:
+#
+#     /bin/bash: CONTRIBUTING.md COPYING COPYING.ja
+#
+# #### Execution Shell on Windows
+#
+# On Windows, the shell invoked is determined by environment variable
+# `RUBYSHELL`, if defined, or `COMSPEC` otherwise; the entire string
+# `command_line` is passed as an argument to `-c` option for `RUBYSHELL`, as
+# well as `/bin/sh`, and [/c
+# option](https://learn.microsoft.com/en-us/windows-server/administration/window
+# s-commands/cmd) for `COMSPEC`.  The shell is invoked automatically in the
+# following cases:
+#
+# *   The command is a built-in of `cmd.exe`, such as `echo`.
+# *   The executable file is a batch file; its name ends with `.bat` or `.cmd`.
+#
+# Note that the command will still be invoked as `command_line` form even when
+# called in `exe_path` form, because `cmd.exe` does not accept a script name
+# like `/bin/sh` does but only works with `/c` option.
+#
+# The standard shell `cmd.exe` performs environment variable expansion but does
+# not have globbing functionality:
+#
+# Example:
+#
+#     system("echo %COMSPEC%: C*")' # => true
+#
+# Output:
+#
+#     C:\WINDOWS\system32\cmd.exe: C*
+#
+# ## What's Here
+#
+# ### Current-Process Getters
+#
+# *   ::argv0: Returns the process name as a frozen string.
+# *   ::egid: Returns the effective group ID.
+# *   ::euid: Returns the effective user ID.
+# *   ::getpgrp: Return the process group ID.
+# *   ::getrlimit: Returns the resource limit.
+# *   ::gid: Returns the (real) group ID.
+# *   ::pid: Returns the process ID.
+# *   ::ppid: Returns the process ID of the parent process.
+# *   ::uid: Returns the (real) user ID.
+#
+# ### Current-Process Setters
+#
+# *   ::egid=: Sets the effective group ID.
+# *   ::euid=: Sets the effective user ID.
+# *   ::gid=: Sets the (real) group ID.
+# *   ::setproctitle: Sets the process title.
+# *   ::setpgrp: Sets the process group ID of the process to zero.
+# *   ::setrlimit: Sets a resource limit.
+# *   ::setsid: Establishes the process as a new session and process group
+#     leader, with no controlling tty.
+# *   ::uid=: Sets the user ID.
+#
+# ### Current-Process Execution
+#
+# *   ::abort: Immediately terminates the process.
+# *   ::daemon: Detaches the process from its controlling terminal and continues
+#     running it in the background as system daemon.
+# *   ::exec: Replaces the process by running a given external command.
+# *   ::exit: Initiates process termination by raising exception SystemExit
+#     (which may be caught).
+# *   ::exit!: Immediately exits the process.
+# *   ::warmup: Notifies the Ruby virtual machine that the boot sequence for the
+#     application is completed, and that the VM may begin optimizing the
+#     application.
+#
+# ### Child Processes
+#
+# *   ::detach: Guards against a child process becoming a zombie.
+# *   ::fork: Creates a child process.
+# *   ::kill: Sends a given signal to processes.
+# *   ::spawn: Creates a child process.
+# *   ::wait, ::waitpid: Waits for a child process to exit; returns its process
+#     ID.
+# *   ::wait2, ::waitpid2: Waits for a child process to exit; returns its
+#     process ID and status.
+# *   ::waitall: Waits for all child processes to exit; returns their process
+#     IDs and statuses.
+#
+# ### Process Groups
+#
+# *   ::getpgid: Returns the process group ID for a process.
+# *   ::getpriority: Returns the scheduling priority for a process, process
+#     group, or user.
+# *   ::getsid: Returns the session ID for a process.
+# *   ::groups: Returns an array of the group IDs in the supplemental group
+#     access list for this process.
+# *   ::groups=: Sets the supplemental group access list to the given array of
+#     group IDs.
+# *   ::initgroups: Initializes the supplemental group access list.
+# *   ::last_status: Returns the status of the last executed child process in
+#     the current thread.
+# *   ::maxgroups: Returns the maximum number of group IDs allowed in the
+#     supplemental group access list.
+# *   ::maxgroups=: Sets the maximum number of group IDs allowed in the
+#     supplemental group access list.
+# *   ::setpgid: Sets the process group ID of a process.
+# *   ::setpriority: Sets the scheduling priority for a process, process group,
+#     or user.
+#
+# ### Timing
+#
+# *   ::clock_getres: Returns the resolution of a system clock.
+# *   ::clock_gettime: Returns the time from a system clock.
+# *   ::times: Returns a Process::Tms object containing times for the current
+#     process and its child processes.
 #
 module Process
   # <!--
@@ -26,6 +411,12 @@ module Process
   # You can add custom code before and after fork events by overriding this
   # method.
   #
+  # Note: Process.daemon may be implemented using fork(2) BUT does not go through
+  # this method. Thus, depending on your reason to hook into this method, you may
+  # also want to hook into that one. See [this
+  # issue](https://bugs.ruby-lang.org/issues/18911) for a more detailed discussion
+  # of this.
+  #
   def self._fork: () -> Integer
 
   # <!--
@@ -42,203 +433,193 @@ module Process
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.clock_getres(clock_id [, unit])   -> number
+  #   - Process.clock_getres(clock_id, unit = :float_second)  -> number
   # -->
-  # Returns an estimate of the resolution of a `clock_id` using the POSIX
-  # `clock_getres()` function.
-  #
-  # Note the reported resolution is often inaccurate on most platforms due to
-  # underlying bugs for this function and therefore the reported resolution often
-  # differs from the actual resolution of the clock in practice. Inaccurate
-  # reported resolutions have been observed for various clocks including
-  # CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW when using Linux, macOS, BSD or AIX
-  # platforms, when using ARM processors, or when using virtualization.
+  # Returns a clock resolution as determined by POSIX function
+  # [clock_getres()](https://man7.org/linux/man-pages/man3/clock_getres.3.html):
   #
-  # `clock_id` specifies a kind of clock. See the document of
-  # `Process.clock_gettime` for details. `clock_id` can be a symbol as for
-  # `Process.clock_gettime`.
+  #     Process.clock_getres(:CLOCK_REALTIME) # => 1.0e-09
   #
-  # If the given `clock_id` is not supported, Errno::EINVAL is raised.
+  # See Process.clock_gettime for the values of `clock_id` and `unit`.
   #
-  # `unit` specifies the type of the return value. `Process.clock_getres` accepts
-  # `unit` as `Process.clock_gettime`. The default value, `:float_second`, is also
-  # the same as `Process.clock_gettime`.
+  # Examples:
   #
-  # `Process.clock_getres` also accepts `:hertz` as `unit`. `:hertz` means the
-  # reciprocal of `:float_second`.
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond) # => 0.001
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond) # => 1.0e-06
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :float_second)      # => 1.0e-09
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :microsecond)       # => 0
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :millisecond)       # => 0
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond)        # => 1
+  #     Process.clock_getres(:CLOCK_PROCESS_CPUTIME_ID, :second)            # => 0
   #
-  # `:hertz` can be used to obtain the exact value of the clock ticks per second
-  # for the times() function and CLOCKS_PER_SEC for the clock() function.
+  # In addition to the values for `unit` supported in Process.clock_gettime, this
+  # method supports `:hertz`, the integer number of clock ticks per second (which
+  # is the reciprocal of `:float_second`):
   #
-  # `Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz)` returns
-  # the clock ticks per second.
+  #     Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz)        # => 100.0
+  #     Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :float_second) # => 0.01
   #
-  # `Process.clock_getres(:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz)` returns
-  # CLOCKS_PER_SEC.
-  #
-  #     p Process.clock_getres(Process::CLOCK_MONOTONIC)
-  #     #=> 1.0e-09
+  # **Accuracy**: Note that the returned resolution may be inaccurate on some
+  # platforms due to underlying bugs. Inaccurate resolutions have been reported
+  # for various clocks including `:CLOCK_MONOTONIC` and `:CLOCK_MONOTONIC_RAW` on
+  # Linux, macOS, BSD or AIX platforms, when using ARM processors, or when using
+  # virtualization.
   #
   def self.clock_getres: (Symbol | Integer clock_id, ?Symbol unit) -> (Float | Integer)
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.clock_gettime(clock_id [, unit])   -> number
-  # -->
-  # Returns a time returned by POSIX clock_gettime() function.
-  #
-  #     p Process.clock_gettime(Process::CLOCK_MONOTONIC)
-  #     #=> 896053.968060096
-  #
-  # `clock_id` specifies a kind of clock. It is specified as a constant which
-  # begins with `Process::CLOCK_` such as Process::CLOCK_REALTIME and
-  # Process::CLOCK_MONOTONIC.
-  #
-  # The supported constants depends on OS and version. Ruby provides following
-  # types of `clock_id` if available.
-  #
-  # CLOCK_REALTIME
-  # :   SUSv2 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 2.1, macOS
-  #     10.12, Windows-8/Server-2012
-  # CLOCK_MONOTONIC
-  # :   SUSv3 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0, OpenBSD 3.4, macOS
-  #     10.12, Windows-2000
-  # CLOCK_PROCESS_CPUTIME_ID
-  # :   SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3, OpenBSD 5.4, macOS 10.12
-  # CLOCK_THREAD_CPUTIME_ID
-  # :   SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD 5.4, macOS 10.12
-  # CLOCK_VIRTUAL
-  # :   FreeBSD 3.0, OpenBSD 2.1
-  # CLOCK_PROF
-  # :   FreeBSD 3.0, OpenBSD 2.1
-  # CLOCK_REALTIME_FAST
-  # :   FreeBSD 8.1
-  # CLOCK_REALTIME_PRECISE
-  # :   FreeBSD 8.1
-  # CLOCK_REALTIME_COARSE
-  # :   Linux 2.6.32
-  # CLOCK_REALTIME_ALARM
-  # :   Linux 3.0
-  # CLOCK_MONOTONIC_FAST
-  # :   FreeBSD 8.1
-  # CLOCK_MONOTONIC_PRECISE
-  # :   FreeBSD 8.1
-  # CLOCK_MONOTONIC_COARSE
-  # :   Linux 2.6.32
-  # CLOCK_MONOTONIC_RAW
-  # :   Linux 2.6.28, macOS 10.12
-  # CLOCK_MONOTONIC_RAW_APPROX
-  # :   macOS 10.12
-  # CLOCK_BOOTTIME
-  # :   Linux 2.6.39
-  # CLOCK_BOOTTIME_ALARM
-  # :   Linux 3.0
-  # CLOCK_UPTIME
-  # :   FreeBSD 7.0, OpenBSD 5.5
-  # CLOCK_UPTIME_FAST
-  # :   FreeBSD 8.1
-  # CLOCK_UPTIME_RAW
-  # :   macOS 10.12
-  # CLOCK_UPTIME_RAW_APPROX
-  # :   macOS 10.12
-  # CLOCK_UPTIME_PRECISE
-  # :   FreeBSD 8.1
-  # CLOCK_SECOND
-  # :   FreeBSD 8.1
-  # CLOCK_TAI
-  # :   Linux 3.10
-  #
+  #   - Process.clock_gettime(clock_id, unit = :float_second) -> number
+  # -->
+  # Returns a clock time as determined by POSIX function
+  # [clock_gettime()](https://man7.org/linux/man-pages/man3/clock_gettime.3.html):
+  #
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID) # => 198.650379677
+  #
+  # Argument `clock_id` should be a symbol or a constant that specifies the clock
+  # whose time is to be returned; see below.
+  #
+  # Optional argument `unit` should be a symbol that specifies the unit to be used
+  # in the returned clock time; see below.
+  #
+  # **Argument `clock_id`**
+  #
+  # Argument `clock_id` specifies the clock whose time is to be returned; it may
+  # be a constant such as `Process::CLOCK_REALTIME`, or a symbol shorthand such as
+  # `:CLOCK_REALTIME`.
+  #
+  # The supported clocks depend on the underlying operating system; this method
+  # supports the following clocks on the indicated platforms (raises Errno::EINVAL
+  # if called with an unsupported clock):
+  #
+  # *   `:CLOCK_BOOTTIME`: Linux 2.6.39.
+  # *   `:CLOCK_BOOTTIME_ALARM`: Linux 3.0.
+  # *   `:CLOCK_MONOTONIC`: SUSv3 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0,
+  #     OpenBSD 3.4, macOS 10.12, Windows-2000.
+  # *   `:CLOCK_MONOTONIC_COARSE`: Linux 2.6.32.
+  # *   `:CLOCK_MONOTONIC_FAST`: FreeBSD 8.1.
+  # *   `:CLOCK_MONOTONIC_PRECISE`: FreeBSD 8.1.
+  # *   `:CLOCK_MONOTONIC_RAW`: Linux 2.6.28, macOS 10.12.
+  # *   `:CLOCK_MONOTONIC_RAW_APPROX`: macOS 10.12.
+  # *   `:CLOCK_PROCESS_CPUTIME_ID`: SUSv3 to 4, Linux 2.5.63, FreeBSD 9.3,
+  #     OpenBSD 5.4, macOS 10.12.
+  # *   `:CLOCK_PROF`: FreeBSD 3.0, OpenBSD 2.1.
+  # *   `:CLOCK_REALTIME`: SUSv2 to 4, Linux 2.5.63, FreeBSD 3.0, NetBSD 2.0,
+  #     OpenBSD 2.1, macOS 10.12, Windows-8/Server-2012. Time.now is recommended
+  #     over +:CLOCK_REALTIME:.
+  # *   `:CLOCK_REALTIME_ALARM`: Linux 3.0.
+  # *   `:CLOCK_REALTIME_COARSE`: Linux 2.6.32.
+  # *   `:CLOCK_REALTIME_FAST`: FreeBSD 8.1.
+  # *   `:CLOCK_REALTIME_PRECISE`: FreeBSD 8.1.
+  # *   `:CLOCK_SECOND`: FreeBSD 8.1.
+  # *   `:CLOCK_TAI`: Linux 3.10.
+  # *   `:CLOCK_THREAD_CPUTIME_ID`: SUSv3 to 4, Linux 2.5.63, FreeBSD 7.1, OpenBSD
+  #     5.4, macOS 10.12.
+  # *   `:CLOCK_UPTIME`: FreeBSD 7.0, OpenBSD 5.5.
+  # *   `:CLOCK_UPTIME_FAST`: FreeBSD 8.1.
+  # *   `:CLOCK_UPTIME_PRECISE`: FreeBSD 8.1.
+  # *   `:CLOCK_UPTIME_RAW`: macOS 10.12.
+  # *   `:CLOCK_UPTIME_RAW_APPROX`: macOS 10.12.
+  # *   `:CLOCK_VIRTUAL`: FreeBSD 3.0, OpenBSD 2.1.
   #
   # Note that SUS stands for Single Unix Specification. SUS contains POSIX and
-  # clock_gettime is defined in the POSIX part. SUS defines CLOCK_REALTIME
-  # mandatory but CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID and
-  # CLOCK_THREAD_CPUTIME_ID are optional.
-  #
-  # Also, several symbols are accepted as `clock_id`. There are emulations for
-  # clock_gettime().
-  #
-  # For example, Process::CLOCK_REALTIME is defined as
-  # `:GETTIMEOFDAY_BASED_CLOCK_REALTIME` when clock_gettime() is not available.
-  #
-  # Emulations for `CLOCK_REALTIME`:
-  # :GETTIMEOFDAY_BASED_CLOCK_REALTIME
-  # :   Use gettimeofday() defined by SUS. (SUSv4 obsoleted it, though.) The
-  #     resolution is 1 microsecond.
-  # :TIME_BASED_CLOCK_REALTIME
-  # :   Use time() defined by ISO C. The resolution is 1 second.
-  #
-  #
-  # Emulations for `CLOCK_MONOTONIC`:
-  # :MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC
-  # :   Use mach_absolute_time(), available on Darwin. The resolution is CPU
-  #     dependent.
-  # :TIMES_BASED_CLOCK_MONOTONIC
-  # :   Use the result value of times() defined by POSIX. POSIX defines it as
-  #     "times() shall return the elapsed real time, in clock ticks, since an
-  #     arbitrary point in the past (for example, system start-up time)". For
-  #     example, GNU/Linux returns a value based on jiffies and it is monotonic.
-  #     However, 4.4BSD uses gettimeofday() and it is not monotonic. (FreeBSD uses
-  #     clock_gettime(CLOCK_MONOTONIC) instead, though.) The resolution is the
-  #     clock tick. "getconf CLK_TCK" command shows the clock ticks per second.
-  #     (The clock ticks per second is defined by HZ macro in older systems.) If
-  #     it is 100 and clock_t is 32 bits integer type, the resolution is 10
-  #     millisecond and cannot represent over 497 days.
-  #
-  #
-  # Emulations for `CLOCK_PROCESS_CPUTIME_ID`:
-  # :GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID
-  # :   Use getrusage() defined by SUS. getrusage() is used with RUSAGE_SELF to
-  #     obtain the time only for the calling process (excluding the time for child
-  #     processes). The result is addition of user time (ru_utime) and system time
-  #     (ru_stime). The resolution is 1 microsecond.
-  # :TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID
-  # :   Use times() defined by POSIX. The result is addition of user time
-  #     (tms_utime) and system time (tms_stime). tms_cutime and tms_cstime are
-  #     ignored to exclude the time for child processes. The resolution is the
-  #     clock tick. "getconf CLK_TCK" command shows the clock ticks per second.
-  #     (The clock ticks per second is defined by HZ macro in older systems.) If
-  #     it is 100, the resolution is 10 millisecond.
-  # :CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID
-  # :   Use clock() defined by ISO C. The resolution is 1/CLOCKS_PER_SEC.
-  #     CLOCKS_PER_SEC is the C-level macro defined by time.h. SUS defines
-  #     CLOCKS_PER_SEC is 1000000. Non-Unix systems may define it a different
-  #     value, though. If CLOCKS_PER_SEC is 1000000 as SUS, the resolution is 1
-  #     microsecond. If CLOCKS_PER_SEC is 1000000 and clock_t is 32 bits integer
-  #     type, it cannot represent over 72 minutes.
-  #
-  #
-  # If the given `clock_id` is not supported, Errno::EINVAL is raised.
-  #
-  # `unit` specifies a type of the return value.
-  #
-  # :float_second
-  # :   number of seconds as a float (default)
-  # :float_millisecond
-  # :   number of milliseconds as a float
-  # :float_microsecond
-  # :   number of microseconds as a float
-  # :second
-  # :   number of seconds as an integer
-  # :millisecond
-  # :   number of milliseconds as an integer
-  # :microsecond
-  # :   number of microseconds as an integer
-  # :nanosecond
-  # :   number of nanoseconds as an integer
-  #
+  # clock_gettime is defined in the POSIX part. SUS defines `:CLOCK_REALTIME` as
+  # mandatory but `:CLOCK_MONOTONIC`, `:CLOCK_PROCESS_CPUTIME_ID`, and
+  # `:CLOCK_THREAD_CPUTIME_ID` are optional.
+  #
+  # Certain emulations are used when the given `clock_id` is not supported
+  # directly:
+  #
+  # *   Emulations for `:CLOCK_REALTIME`:
+  #
+  #     *   `:GETTIMEOFDAY_BASED_CLOCK_REALTIME`: Use gettimeofday() defined by
+  #         SUS (deprecated in SUSv4). The resolution is 1 microsecond.
+  #     *   `:TIME_BASED_CLOCK_REALTIME`: Use time() defined by ISO C. The
+  #         resolution is 1 second.
+  #
+  # *   Emulations for `:CLOCK_MONOTONIC`:
+  #
+  #     *   `:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC`: Use mach_absolute_time(),
+  #         available on Darwin. The resolution is CPU dependent.
+  #     *   `:TIMES_BASED_CLOCK_MONOTONIC`: Use the result value of times()
+  #         defined by POSIX, thus:
+  # > Upon successful completion, times() shall return the elapsed real
+  #           time, in clock ticks, since an arbitrary point in the past (for
+  #           example, system start-up time).
+  #
+  # > For example, GNU/Linux returns a value based on jiffies and it is
+  #         monotonic. However, 4.4BSD uses gettimeofday() and it is not
+  #         monotonic. (FreeBSD uses `:CLOCK_MONOTONIC` instead, though.)
+  #
+  #         The resolution is the clock tick. "getconf CLK_TCK" command shows the
+  #         clock ticks per second. (The clock ticks-per-second is defined by HZ
+  #         macro in older systems.) If it is 100 and clock_t is 32 bits integer
+  #         type, the resolution is 10 millisecond and cannot represent over 497
+  #         days.
+  #
+  # *   Emulations for `:CLOCK_PROCESS_CPUTIME_ID`:
+  #
+  #     *   `:GETRUSAGE_BASED_CLOCK_PROCESS_CPUTIME_ID`: Use getrusage() defined
+  #         by SUS. getrusage() is used with RUSAGE_SELF to obtain the time only
+  #         for the calling process (excluding the time for child processes). The
+  #         result is addition of user time (ru_utime) and system time (ru_stime).
+  #         The resolution is 1 microsecond.
+  #     *   `:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID`: Use times() defined by POSIX.
+  #         The result is addition of user time (tms_utime) and system time
+  #         (tms_stime). tms_cutime and tms_cstime are ignored to exclude the time
+  #         for child processes. The resolution is the clock tick. "getconf
+  #         CLK_TCK" command shows the clock ticks per second. (The clock ticks
+  #         per second is defined by HZ macro in older systems.) If it is 100, the
+  #         resolution is 10 millisecond.
+  #     *   `:CLOCK_BASED_CLOCK_PROCESS_CPUTIME_ID`: Use clock() defined by ISO C.
+  #         The resolution is `1/CLOCKS_PER_SEC`. `CLOCKS_PER_SEC` is the C-level
+  #         macro defined by time.h. SUS defines `CLOCKS_PER_SEC` as 1000000;
+  #         other systems may define it differently. If `CLOCKS_PER_SEC` is
+  #         1000000 (as in SUS), the resolution is 1 microsecond. If
+  #         `CLOCKS_PER_SEC` is 1000000 and clock_t is a 32-bit integer type, it
+  #         cannot represent over 72 minutes.
+  #
+  # **Argument `unit`**
+  #
+  # Optional argument `unit` (default `:float_second`) specifies the unit for the
+  # returned value.
+  #
+  # *   `:float_microsecond`: Number of microseconds as a float.
+  # *   `:float_millisecond`: Number of milliseconds as a float.
+  # *   `:float_second`: Number of seconds as a float.
+  # *   `:microsecond`: Number of microseconds as an integer.
+  # *   `:millisecond`: Number of milliseconds as an integer.
+  # *   `:nanosecond`: Number of nanoseconds as an integer.
+  # *   `::second`: Number of seconds as an integer.
+  #
+  # Examples:
+  #
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_microsecond)
+  #     # => 203605054.825
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_millisecond)
+  #     # => 203643.696848
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :float_second)
+  #     # => 203.762181929
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :microsecond)
+  #     # => 204123212
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :millisecond)
+  #     # => 204298
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :nanosecond)
+  #     # => 204602286036
+  #     Process.clock_gettime(:CLOCK_PROCESS_CPUTIME_ID, :second)
+  #     # => 204
   #
   # The underlying function, clock_gettime(), returns a number of nanoseconds.
   # Float object (IEEE 754 double) is not enough to represent the return value for
-  # CLOCK_REALTIME. If the exact nanoseconds value is required, use `:nanoseconds`
-  # as the `unit`.
+  # `:CLOCK_REALTIME`. If the exact nanoseconds value is required, use
+  # `:nanosecond` as the `unit`.
   #
-  # The origin (zero) of the returned value varies. For example, system start up
-  # time, process start up time, the Epoch, etc.
+  # The origin (time zero) of the returned value is system-dependent, and may be,
+  # for example, system start up time, process start up time, the Epoch, etc.
   #
-  # The origin in CLOCK_REALTIME is defined as the Epoch (1970-01-01 00:00:00
-  # UTC). But some systems count leap seconds and others doesn't. So the result
-  # can be interpreted differently across systems. Time.now is recommended over
-  # CLOCK_REALTIME.
+  # The origin in `:CLOCK_REALTIME` is defined as the Epoch: `1970-01-01 00:00:00
+  # UTC`; some systems count leap seconds and others don't, so the result may vary
+  # across systems.
   #
   def self.clock_gettime: (Symbol | Integer clock_id) -> Float
                         | (Symbol | Integer clock_id, :float_second | :float_millisecond | :float_microsecond unit) -> Float
@@ -246,210 +627,233 @@ module Process
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.daemon()                        -> 0
-  #   - Process.daemon(nochdir=nil,noclose=nil) -> 0
+  #   - Process.daemon(nochdir = nil, noclose = nil) -> 0
   # -->
-  # Detach the process from controlling terminal and run in the background as
-  # system daemon.  Unless the argument nochdir is true (i.e. non false), it
-  # changes the current working directory to the root ("/"). Unless the argument
-  # noclose is true, daemon() will redirect standard input, standard output and
-  # standard error to /dev/null. Return zero on success, or raise one of Errno::*.
+  # Detaches the current process from its controlling terminal and runs it in the
+  # background as system daemon; returns zero.
+  #
+  # By default:
+  #
+  # *   Changes the current working directory to the root directory.
+  # *   Redirects $stdin, $stdout, and $stderr to the null device.
+  #
+  # If optional argument `nochdir` is `true`, does not change the current working
+  # directory.
+  #
+  # If optional argument `noclose` is `true`, does not redirect $stdin, $stdout,
+  # or $stderr.
   #
   def self.daemon: (?untyped nochdir, ?untyped noclose) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.detach(pid)   -> thread
+  #   - Process.detach(pid) -> thread
   # -->
-  # Some operating systems retain the status of terminated child processes until
-  # the parent collects that status (normally using some variant of `wait()`). If
-  # the parent never collects this status, the child stays around as a *zombie*
-  # process. Process::detach prevents this by setting up a separate Ruby thread
-  # whose sole job is to reap the status of the process *pid* when it terminates.
-  # Use #detach only when you do not intend to explicitly wait for the child to
-  # terminate.
+  # Avoids the potential for a child process to become a [zombie
+  # process](https://en.wikipedia.org/wiki/Zombie_process). Process.detach
+  # prevents this by setting up a separate Ruby thread whose sole job is to reap
+  # the status of the process *pid* when it terminates.
   #
-  # The waiting thread returns the exit status of the detached process when it
-  # terminates, so you can use Thread#join to know the result.  If specified *pid*
-  # is not a valid child process ID, the thread returns `nil` immediately.
+  # This method is needed only when the parent process will never wait for the
+  # child process.
   #
-  # The waiting thread has #pid method which returns the pid.
+  # This example does not reap the second child process; that process appears as a
+  # zombie in the process status (`ps`) output:
   #
-  # In this first example, we don't reap the first child process, so it appears as
-  # a zombie in the process status display.
+  #     pid = Process.spawn('ruby', '-e', 'exit 13') # => 312691
+  #     sleep(1)
+  #     # Find zombies.
+  #     system("ps -ho pid,state -p #{pid}")
   #
-  #     p1 = fork { sleep 0.1 }
-  #     p2 = fork { sleep 0.2 }
-  #     Process.waitpid(p2)
-  #     sleep 2
-  #     system("ps -ho pid,state -p #{p1}")
+  # Output:
   #
-  # *produces:*
+  #     312716 Z
   #
-  #     27389 Z
+  # This example also does not reap the second child process, but it does detach
+  # the process so that it does not become a zombie:
   #
-  # In the next example, Process::detach is used to reap the child automatically.
+  #     pid = Process.spawn('ruby', '-e', 'exit 13') # => 313213
+  #     thread = Process.detach(pid)
+  #     sleep(1)
+  #     # => #<Process::Waiter:0x00007f038f48b838 run>
+  #     system("ps -ho pid,state -p #{pid}")        # Finds no zombies.
   #
-  #     p1 = fork { sleep 0.1 }
-  #     p2 = fork { sleep 0.2 }
-  #     Process.detach(p1)
-  #     Process.waitpid(p2)
-  #     sleep 2
-  #     system("ps -ho pid,state -p #{p1}")
+  # The waiting thread can return the pid of the detached child process:
   #
-  # *(produces no output)*
+  #     thread.join.pid                       # => 313262
   #
-  def self.detach: (Integer pid) -> Thread
+  def self.detach: (Integer pid) -> Process::Waiter
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.egid          -> integer
-  #   - Process::GID.eid      -> integer
-  #   - Process::Sys.geteid   -> integer
+  #   - Process.egid        -> integer
+  #   - Process::GID.eid    -> integer
+  #   - Process::Sys.geteid -> integer
   # -->
-  # Returns the effective group ID for this process. Not available on all
-  # platforms.
+  # Returns the effective group ID for the current process:
   #
-  #     Process.egid   #=> 500
+  #     Process.egid # => 500
+  #
+  # Not available on all platforms.
   #
   def self.egid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.egid = integer   -> integer
+  #   - Process.egid = new_egid -> new_egid
   # -->
-  # Sets the effective group ID for this process. Not available on all platforms.
+  # Sets the effective group ID for the current process.
+  #
+  # Not available on all platforms.
   #
   def self.egid=: (Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.euid           -> integer
-  #   - Process::UID.eid       -> integer
-  #   - Process::Sys.geteuid   -> integer
+  #   - Process.euid         -> integer
+  #   - Process::UID.eid     -> integer
+  #   - Process::Sys.geteuid -> integer
   # -->
-  # Returns the effective user ID for this process.
+  # Returns the effective user ID for the current process.
   #
-  #     Process.euid   #=> 501
+  #     Process.euid # => 501
   #
   def self.euid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.euid= user
+  #   - Process.euid = new_euid -> new_euid
   # -->
-  # Sets the effective user ID for this process. Not available on all platforms.
+  # Sets the effective user ID for the current process.
+  #
+  # Not available on all platforms.
   #
   def self.euid=: (Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.getpgid(pid)   -> integer
+  #   - Process.getpgid(pid) -> integer
   # -->
-  # Returns the process group ID for the given process id. Not available on all
-  # platforms.
+  # Returns the process group ID for the given process ID +pid+:
+  #
+  #       Process.getpgid(Process.ppid) # => 25527
   #
-  #     Process.getpgid(Process.ppid())   #=> 25527
+  # Not available on all platforms.
   #
   def self.getpgid: (Integer pid) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.getpgrp   -> integer
+  #   - Process.getpgrp -> integer
   # -->
-  # Returns the process group ID for this process. Not available on all platforms.
+  # Returns the process group ID for the current process:
   #
-  #     Process.getpgid(0)   #=> 25527
-  #     Process.getpgrp      #=> 25527
+  #     Process.getpgid(0) # => 25527
+  #     Process.getpgrp    # => 25527
   #
   def self.getpgrp: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.getpriority(kind, integer)   -> integer
+  #   - Process.getpriority(kind, id)   -> integer
   # -->
-  # Gets the scheduling priority for specified process, process group, or user.
-  # *kind* indicates the kind of entity to find: one of Process::PRIO_PGRP,
-  # Process::PRIO_USER, or Process::PRIO_PROCESS. *integer* is an id indicating
-  # the particular process, process group, or user (an id of 0 means *current*).
-  # Lower priorities are more favorable for scheduling. Not available on all
-  # platforms.
+  # Returns the scheduling priority for specified process, process group, or user.
+  #
+  # Argument `kind` is one of:
+  #
+  # *   Process::PRIO_PROCESS: return priority for process.
+  # *   Process::PRIO_PGRP: return priority for process group.
+  # *   Process::PRIO_USER: return priority for user.
   #
-  #     Process.getpriority(Process::PRIO_USER, 0)      #=> 19
-  #     Process.getpriority(Process::PRIO_PROCESS, 0)   #=> 19
+  # Argument `id` is the ID for the process, process group, or user; zero
+  # specified the current ID for `kind`.
+  #
+  # Examples:
+  #
+  #     Process.getpriority(Process::PRIO_USER, 0)    # => 19
+  #     Process.getpriority(Process::PRIO_PROCESS, 0) # => 19
+  #
+  # Not available on all platforms.
   #
   def self.getpriority: (Integer kind, Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.getrlimit(resource)   -> [cur_limit, max_limit]
+  #   - Process.getrlimit(resource) -> [cur_limit, max_limit]
   # -->
-  # Gets the resource limit of the process. *cur_limit* means current (soft) limit
-  # and *max_limit* means maximum (hard) limit.
+  # Returns a 2-element array of the current (soft) limit and maximum (hard) limit
+  # for the given `resource`.
+  #
+  # Argument `resource` specifies the resource whose limits are to be returned;
+  # see Process.setrlimit.
+  #
+  # Each of the returned values `cur_limit` and `max_limit` is an integer; see
+  # Process.setrlimit.
+  #
+  # Example:
   #
-  # *resource* indicates the kind of resource to limit. It is specified as a
-  # symbol such as `:CORE`, a string such as `"CORE"` or a constant such as
-  # Process::RLIMIT_CORE. See Process.setrlimit for details.
+  #     Process.getrlimit(:CORE) # => [0, 18446744073709551615]
   #
-  # *cur_limit* and *max_limit* may be Process::RLIM_INFINITY,
-  # Process::RLIM_SAVED_MAX or Process::RLIM_SAVED_CUR. See Process.setrlimit and
-  # the system getrlimit(2) manual for details.
+  # See Process.setrlimit.
   #
-  def self.getrlimit: (Symbol | String | Integer resource) -> [ Integer, Integer ]
+  # Not available on all platforms.
+  #
+  def self.getrlimit: (interned | Integer resource) -> [ Integer, Integer ]
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.getsid()      -> integer
-  #   - Process.getsid(pid)   -> integer
+  #   - Process.getsid(pid = nil) -> integer
   # -->
-  # Returns the session ID for the given process id. If not given, return current
-  # process sid. Not available on all platforms.
+  # Returns the session ID of the given process ID `pid`, or of the current
+  # process if not given:
   #
-  #     Process.getsid()                #=> 27422
-  #     Process.getsid(0)               #=> 27422
-  #     Process.getsid(Process.pid())   #=> 27422
+  #     Process.getsid                # => 27422
+  #     Process.getsid(0)             # => 27422
+  #     Process.getsid(Process.pid()) # => 27422
+  #
+  # Not available on all platforms.
   #
   def self.getsid: (?Integer pid) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.gid           -> integer
-  #   - Process::GID.rid      -> integer
-  #   - Process::Sys.getgid   -> integer
+  #   - Process.gid         -> integer
+  #   - Process::GID.rid    -> integer
+  #   - Process::Sys.getgid -> integer
   # -->
-  # Returns the (real) group ID for this process.
+  # Returns the (real) group ID for the current process:
   #
-  #     Process.gid   #=> 500
+  #     Process.gid # => 1000
   #
   def self.gid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.gid= integer   -> integer
+  #   - Process.gid = new_gid -> new_gid
   # -->
-  # Sets the group ID for this process.
+  # Sets the group ID for the current process to `new_gid`:
+  #
+  #     Process.gid = 1000 # => 1000
   #
   def self.gid=: (Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.groups   -> array
+  #   - Process.groups -> array
   # -->
-  # Get an Array of the group IDs in the supplemental group access list for this
-  # process.
-  #
-  #     Process.groups   #=> [27, 6, 10, 11]
+  # Returns an array of the group IDs in the supplemental group access list for
+  # the current process:
   #
-  # Note that this method is just a wrapper of getgroups(2). This means that the
-  # following characteristics of the result completely depend on your system:
+  #     Process.groups # => [4, 24, 27, 30, 46, 122, 135, 136, 1000]
   #
-  # *   the result is sorted
-  # *   the result includes effective GIDs
-  # *   the result does not include duplicated GIDs
+  # These properties of the returned array are system-dependent:
   #
+  # *   Whether (and how) the array is sorted.
+  # *   Whether the array includes effective group IDs.
+  # *   Whether the array includes duplicate group IDs.
+  # *   Whether the array size exceeds the value of Process.maxgroups.
   #
-  # You can make sure to get a sorted unique GID list of the current process by
-  # this expression:
+  # Use this call to get a sorted and unique array:
   #
   #     Process.groups.uniq.sort
   #
@@ -457,132 +861,179 @@ module Process
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.groups= array   -> array
+  #   - Process.groups = new_groups -> new_groups
   # -->
-  # Set the supplemental group access list to the given Array of group IDs.
+  # Sets the supplemental group access list to the given array of group IDs.
   #
-  #     Process.groups   #=> [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
-  #     Process.groups = [27, 6, 10, 11]   #=> [27, 6, 10, 11]
-  #     Process.groups   #=> [27, 6, 10, 11]
+  #     Process.groups                     # => [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
+  #     Process.groups = [27, 6, 10, 11]   # => [27, 6, 10, 11]
+  #     Process.groups                     # => [27, 6, 10, 11]
   #
   def self.groups=: (::Array[Integer] arg0) -> ::Array[Integer]
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.initgroups(username, gid)   -> array
+  #   - Process.initgroups(username, gid) -> array
   # -->
-  # Initializes the supplemental group access list by reading the system group
-  # database and using all groups of which the given user is a member. The group
-  # with the specified *gid* is also added to the list. Returns the resulting
-  # Array of the gids of all the groups in the supplementary group access list.
-  # Not available on all platforms.
+  # Sets the supplemental group access list; the new list includes:
+  #
+  # *   The group IDs of those groups to which the user given by `username`
+  #     belongs.
+  # *   The group ID `gid`.
   #
-  #     Process.groups   #=> [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
-  #     Process.initgroups( "mgranger", 30 )   #=> [30, 6, 10, 11]
-  #     Process.groups   #=> [30, 6, 10, 11]
+  # Example:
+  #
+  #     Process.groups                # => [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
+  #     Process.initgroups('me', 30)  # => [30, 6, 10, 11]
+  #     Process.groups                # => [30, 6, 10, 11]
+  #
+  # Not available on all platforms.
   #
   def self.initgroups: (String username, Integer gid) -> ::Array[Integer]
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.kill(signal, pid, ...)    -> integer
+  #   - Process.kill(signal, *ids) -> count
   # -->
-  # Sends the given signal to the specified process id(s) if *pid* is positive. If
-  # *pid* is zero, *signal* is sent to all processes whose group ID is equal to
-  # the group ID of the process. If *pid* is negative, results are dependent on
-  # the operating system. *signal* may be an integer signal number or a POSIX
-  # signal name (either with or without a `SIG` prefix). If *signal* is negative
-  # (or starts with a minus sign), kills process groups instead of processes. Not
-  # all signals are available on all platforms. The keys and values of Signal.list
-  # are known signal names and numbers, respectively.
+  # Sends a signal to each process specified by `ids` (which must specify at least
+  # one ID); returns the count of signals sent.
+  #
+  # For each given `id`, if `id` is:
+  #
+  # *   Positive, sends the signal to the process whose process ID is `id`.
+  # *   Zero, send the signal to all processes in the current process group.
+  # *   Negative, sends the signal to a system-dependent collection of processes.
+  #
+  # Argument `signal` specifies the signal to be sent; the argument may be:
+  #
+  # *   An integer signal number: e.g., `-29`, `0`, `29`.
+  # *   A signal name (string), with or without leading `'SIG'`, and with or
+  #     without a further prefixed minus sign (`'-'`): e.g.:
+  #
+  #     *   `'SIGPOLL'`.
+  #     *   `'POLL'`,
+  #     *   `'-SIGPOLL'`.
+  #     *   `'-POLL'`.
+  #
+  # *   A signal symbol, with or without leading `'SIG'`, and with or without a
+  #     further prefixed minus sign (`'-'`): e.g.:
+  #
+  #     *   `:SIGPOLL`.
+  #     *   `:POLL`.
+  #     *   `:'-SIGPOLL'`.
+  #     *   `:'-POLL'`.
+  #
+  # If `signal` is:
+  #
+  # *   A non-negative integer, or a signal name or symbol without prefixed `'-'`,
+  #     each process with process ID `id` is signalled.
+  # *   A negative integer, or a signal name or symbol with prefixed `'-'`, each
+  #     process group with group ID `id` is signalled.
+  #
+  # Use method Signal.list to see which signals are supported by Ruby on the
+  # underlying platform; the method returns a hash of the string names and
+  # non-negative integer values of the supported signals. The size and content of
+  # the returned hash varies widely among platforms.
+  #
+  # Additionally, signal `0` is useful to determine if the process exists.
+  #
+  # Example:
   #
   #     pid = fork do
-  #        Signal.trap("HUP") { puts "Ouch!"; exit }
-  #        # ... do some work ...
+  #       Signal.trap('HUP') { puts 'Ouch!'; exit }
+  #       # ... do some work ...
   #     end
   #     # ...
-  #     Process.kill("HUP", pid)
+  #     Process.kill('HUP', pid)
   #     Process.wait
   #
-  # *produces:*
+  # Output:
   #
   #     Ouch!
   #
-  # If *signal* is an integer but wrong for signal, Errno::EINVAL or RangeError
-  # will be raised.  Otherwise unless *signal* is a String or a Symbol, and a
-  # known signal name, ArgumentError will be raised.
+  # Exceptions:
+  #
+  # *   Raises Errno::EINVAL or RangeError if `signal` is an integer but invalid.
+  # *   Raises ArgumentError if `signal` is a string or symbol but invalid.
+  # *   Raises Errno::ESRCH or RangeError if one of `ids` is invalid.
+  # *   Raises Errno::EPERM if needed permissions are not in force.
   #
-  # Also, Errno::ESRCH or RangeError for invalid *pid*, Errno::EPERM when failed
-  # because of no privilege, will be raised.  In these cases, signals may have
-  # been sent to preceding processes.
+  # In the last two cases, signals may have been sent to some processes.
   #
-  def self.kill: (Integer | Symbol | String signal, *Integer pids) -> Integer
+  def self.kill: (Integer | interned signal, *Integer pids) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.maxgroups   -> integer
+  #   - Process.maxgroups -> integer
   # -->
-  # Returns the maximum number of gids allowed in the supplemental group access
-  # list.
+  # Returns the maximum number of group IDs allowed in the supplemental group
+  # access list:
   #
-  #     Process.maxgroups   #=> 32
+  #     Process.maxgroups # => 32
   #
   def self.maxgroups: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.maxgroups= integer   -> integer
+  #   - Process.maxgroups = new_max -> new_max
   # -->
-  # Sets the maximum number of gids allowed in the supplemental group access list.
+  # Sets the maximum number of group IDs allowed in the supplemental group access
+  # list.
   #
   def self.maxgroups=: (Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.pid   -> integer
+  #   - Process.pid -> integer
   # -->
-  # Returns the process id of this process. Not available on all platforms.
+  # Returns the process ID of the current process:
   #
-  #     Process.pid   #=> 27415
+  #     Process.pid # => 15668
   #
   def self.pid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.ppid   -> integer
+  #   - Process.ppid -> integer
   # -->
-  # Returns the process id of the parent of this process. Returns untrustworthy
-  # value on Win32/64. Not available on all platforms.
+  # Returns the process ID of the parent of the current process:
   #
-  #     puts "I am #{Process.pid}"
-  #     Process.fork { puts "Dad is #{Process.ppid}" }
+  #     puts "Pid is #{Process.pid}."
+  #     fork { puts "Parent pid is #{Process.ppid}." }
   #
-  # *produces:*
+  # Output:
   #
-  #     I am 27417
-  #     Dad is 27417
+  #     Pid is 271290.
+  #     Parent pid is 271290.
+  #
+  # May not return a trustworthy value on certain platforms.
   #
   def self.ppid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.setpgid(pid, integer)   -> 0
+  #   - Process.setpgid(pid, pgid) -> 0
   # -->
-  # Sets the process group ID of *pid* (0 indicates this process) to *integer*.
+  # Sets the process group ID for the process given by process ID `pid` to `pgid`.
+  #
   # Not available on all platforms.
   #
   def self.setpgid: (Integer pid, Integer arg0) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.setpriority(kind, integer, priority)   -> 0
+  #   - Process.setpriority(kind, integer, priority) -> 0
   # -->
   # See Process.getpriority.
   #
-  #     Process.setpriority(Process::PRIO_USER, 0, 19)      #=> 0
-  #     Process.setpriority(Process::PRIO_PROCESS, 0, 19)   #=> 0
-  #     Process.getpriority(Process::PRIO_USER, 0)          #=> 19
-  #     Process.getpriority(Process::PRIO_PROCESS, 0)       #=> 19
+  # Examples:
+  #
+  #     Process.setpriority(Process::PRIO_USER, 0, 19)    # => 0
+  #     Process.setpriority(Process::PRIO_PROCESS, 0, 19) # => 0
+  #     Process.getpriority(Process::PRIO_USER, 0)        # => 19
+  #     Process.getpriority(Process::PRIO_PROCESS, 0)     # => 19
+  #
+  # Not available on all platforms.
   #
   def self.setpriority: (Integer kind, Integer arg0, Integer priority) -> Integer
 
@@ -606,256 +1057,449 @@ module Process
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.setrlimit(resource, cur_limit, max_limit)        -> nil
-  #   - Process.setrlimit(resource, cur_limit)                   -> nil
-  # -->
-  # Sets the resource limit of the process. *cur_limit* means current (soft) limit
-  # and *max_limit* means maximum (hard) limit.
-  #
-  # If *max_limit* is not given, *cur_limit* is used.
-  #
-  # *resource* indicates the kind of resource to limit. It should be a symbol such
-  # as `:CORE`, a string such as `"CORE"` or a constant such as
-  # Process::RLIMIT_CORE. The available resources are OS dependent. Ruby may
-  # support following resources.
-  #
-  # AS
-  # :   total available memory (bytes) (SUSv3, NetBSD, FreeBSD, OpenBSD but
-  #     4.4BSD-Lite)
-  # CORE
-  # :   core size (bytes) (SUSv3)
-  # CPU
-  # :   CPU time (seconds) (SUSv3)
-  # DATA
-  # :   data segment (bytes) (SUSv3)
-  # FSIZE
-  # :   file size (bytes) (SUSv3)
-  # MEMLOCK
-  # :   total size for mlock(2) (bytes) (4.4BSD, GNU/Linux)
-  # MSGQUEUE
-  # :   allocation for POSIX message queues (bytes) (GNU/Linux)
-  # NICE
-  # :   ceiling on process's nice(2) value (number) (GNU/Linux)
-  # NOFILE
-  # :   file descriptors (number) (SUSv3)
-  # NPROC
-  # :   number of processes for the user (number) (4.4BSD, GNU/Linux)
-  # RSS
-  # :   resident memory size (bytes) (4.2BSD, GNU/Linux)
-  # RTPRIO
-  # :   ceiling on the process's real-time priority (number) (GNU/Linux)
-  # RTTIME
-  # :   CPU time for real-time process (us) (GNU/Linux)
-  # SBSIZE
-  # :   all socket buffers (bytes) (NetBSD, FreeBSD)
-  # SIGPENDING
-  # :   number of queued signals allowed (signals) (GNU/Linux)
-  # STACK
-  # :   stack size (bytes) (SUSv3)
-  #
-  #
-  # *cur_limit* and *max_limit* may be `:INFINITY`, `"INFINITY"` or
-  # Process::RLIM_INFINITY, which means that the resource is not limited. They may
-  # be Process::RLIM_SAVED_MAX, Process::RLIM_SAVED_CUR and corresponding symbols
-  # and strings too. See system setrlimit(2) manual for details.
-  #
-  # The following example raises the soft limit of core size to the hard limit to
-  # try to make core dump possible.
+  #   - Process.setrlimit(resource, cur_limit, max_limit = cur_limit) -> nil
+  # -->
+  # Sets limits for the current process for the given `resource` to `cur_limit`
+  # (soft limit) and `max_limit` (hard limit); returns `nil`.
+  #
+  # Argument `resource` specifies the resource whose limits are to be set; the
+  # argument may be given as a symbol, as a string, or as a constant beginning
+  # with `Process::RLIMIT_` (e.g., `:CORE`, `'CORE'`, or `Process::RLIMIT_CORE`.
+  #
+  # The resources available and supported are system-dependent, and may include
+  # (here expressed as symbols):
+  #
+  # *   `:AS`: Total available memory (bytes) (SUSv3, NetBSD, FreeBSD, OpenBSD
+  #     except 4.4BSD-Lite).
+  # *   `:CORE`: Core size (bytes) (SUSv3).
+  # *   `:CPU`: CPU time (seconds) (SUSv3).
+  # *   `:DATA`: Data segment (bytes) (SUSv3).
+  # *   `:FSIZE`: File size (bytes) (SUSv3).
+  # *   `:MEMLOCK`: Total size for mlock(2) (bytes) (4.4BSD, GNU/Linux).
+  # *   `:MSGQUEUE`: Allocation for POSIX message queues (bytes) (GNU/Linux).
+  # *   `:NICE`: Ceiling on process's nice(2) value (number) (GNU/Linux).
+  # *   `:NOFILE`: File descriptors (number) (SUSv3).
+  # *   `:NPROC`: Number of processes for the user (number) (4.4BSD, GNU/Linux).
+  # *   `:NPTS`: Number of pseudo terminals (number) (FreeBSD).
+  # *   `:RSS`: Resident memory size (bytes) (4.2BSD, GNU/Linux).
+  # *   `:RTPRIO`: Ceiling on the process's real-time priority (number)
+  #     (GNU/Linux).
+  # *   `:RTTIME`: CPU time for real-time process (us) (GNU/Linux).
+  # *   `:SBSIZE`: All socket buffers (bytes) (NetBSD, FreeBSD).
+  # *   `:SIGPENDING`: Number of queued signals allowed (signals) (GNU/Linux).
+  # *   `:STACK`: Stack size (bytes) (SUSv3).
+  #
+  # Arguments `cur_limit` and `max_limit` may be:
+  #
+  # *   Integers (`max_limit` should not be smaller than `cur_limit`).
+  # *   Symbol `:SAVED_MAX`, string `'SAVED_MAX'`, or constant
+  #     `Process::RLIM_SAVED_MAX`: saved maximum limit.
+  # *   Symbol `:SAVED_CUR`, string `'SAVED_CUR'`, or constant
+  #     `Process::RLIM_SAVED_CUR`: saved current limit.
+  # *   Symbol `:INFINITY`, string `'INFINITY'`, or constant
+  #     `Process::RLIM_INFINITY`: no limit on resource.
+  #
+  # This example raises the soft limit of core size to the hard limit to try to
+  # make core dump possible:
   #
   #     Process.setrlimit(:CORE, Process.getrlimit(:CORE)[1])
   #
-  def self.setrlimit: (Symbol | String | Integer resource, Integer cur_limit, ?Integer max_limit) -> nil
+  # Not available on all platforms.
+  #
+  def self.setrlimit: (interned | Integer resource, Integer cur_limit, ?Integer max_limit) -> nil
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.setsid   -> integer
+  #   - Process.setsid -> integer
   # -->
-  # Establishes this process as a new session and process group leader, with no
-  # controlling tty. Returns the session id. Not available on all platforms.
+  # Establishes the current process as a new session and process group leader,
+  # with no controlling tty; returns the session ID:
   #
-  #     Process.setsid   #=> 27422
+  #     Process.setsid # => 27422
+  #
+  # Not available on all platforms.
   #
   def self.setsid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.times   -> aProcessTms
+  #   - Process.times -> process_tms
   # -->
-  # Returns a `Tms` structure (see Process::Tms) that contains user and system CPU
-  # times for this process, and also for children processes.
+  # Returns a Process::Tms structure that contains user and system CPU times for
+  # the current process, and for its children processes:
   #
-  #     t = Process.times
-  #     [ t.utime, t.stime, t.cutime, t.cstime ]   #=> [0.0, 0.02, 0.00, 0.00]
+  #     Process.times
+  #     # => #<struct Process::Tms utime=55.122118, stime=35.533068, cutime=0.0, cstime=0.002846>
+  #
+  # The precision is platform-defined.
   #
   def self.times: () -> Process::Tms
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.uid           -> integer
-  #   - Process::UID.rid      -> integer
-  #   - Process::Sys.getuid   -> integer
+  #   - Process.uid         -> integer
+  #   - Process::UID.rid    -> integer
+  #   - Process::Sys.getuid -> integer
   # -->
-  # Returns the (real) user ID of this process.
+  # Returns the (real) user ID of the current process.
   #
-  #     Process.uid   #=> 501
+  #     Process.uid # => 1000
   #
   def self.uid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.uid= user   -> numeric
+  #   - Process.uid = new_uid -> new_uid
   # -->
-  # Sets the (user) user ID for this process. Not available on all platforms.
+  # Sets the (user) user ID for the current process to `new_uid`:
+  #
+  #     Process.uid = 1000 # => 1000
+  #
+  # Not available on all platforms.
   #
   def self.uid=: (Integer user) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.wait()                     -> integer
-  #   - Process.wait(pid=-1, flags=0)      -> integer
-  #   - Process.waitpid(pid=-1, flags=0)   -> integer
-  # -->
-  # Waits for a child process to exit, returns its process id, and sets `$?` to a
-  # Process::Status object containing information on that process. Which child it
-  # waits on depends on the value of *pid*:
-  #
-  # > 0
-  # :   Waits for the child whose process ID equals *pid*.
-  #
-  # 0
-  # :   Waits for any child whose process group ID equals that of the calling
-  #     process.
-  #
-  # -1
-  # :   Waits for any child process (the default if no *pid* is given).
+  #   - Process.wait(pid = -1, flags = 0) -> integer
+  # -->
+  # Waits for a suitable child process to exit, returns its process ID, and sets
+  # `$?` to a Process::Status object containing information on that process. Which
+  # child it waits for depends on the value of the given `pid`:
+  #
+  # *   Positive integer: Waits for the child process whose process ID is `pid`:
+  #
+  #         pid0 = Process.spawn('ruby', '-e', 'exit 13') # => 230866
+  #         pid1 = Process.spawn('ruby', '-e', 'exit 14') # => 230891
+  #         Process.wait(pid0)                            # => 230866
+  #         $?                                            # => #<Process::Status: pid 230866 exit 13>
+  #         Process.wait(pid1)                            # => 230891
+  #         $?                                            # => #<Process::Status: pid 230891 exit 14>
+  #         Process.wait(pid0)                            # Raises Errno::ECHILD
+  #
+  # *   `0`: Waits for any child process whose group ID is the same as that of the
+  #     current process:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #         end
+  #         retrieved_pid = Process.wait(0)
+  #         puts "Process.wait(0) returned pid #{retrieved_pid}, which is child 0 pid."
+  #         begin
+  #           Process.wait(0)
+  #         rescue Errno::ECHILD => x
+  #           puts "Raised #{x.class}, because child 1 process group ID differs from parent process group ID."
+  #         end
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 225764.
+  #         Child 0 pid is 225788
+  #         Child 0 process group ID is 225764 (same as parent's).
+  #         Child 1 pid is 225789
+  #         Child 1 process group ID is 225789 (different from parent's).
+  #         Process.wait(0) returned pid 225788, which is child 0 pid.
+  #         Raised Errno::ECHILD, because child 1 process group ID differs from parent process group ID.
+  #
+  # *   `-1` (default): Waits for any child process:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #           sleep 3 # To force child 1 to exit later than child 0 exit.
+  #         end
+  #         child_pids = [child0_pid, child1_pid]
+  #         retrieved_pid = Process.wait(-1)
+  #         puts child_pids.include?(retrieved_pid)
+  #         retrieved_pid = Process.wait(-1)
+  #         puts child_pids.include?(retrieved_pid)
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 228736.
+  #         Child 0 pid is 228758
+  #         Child 0 process group ID is 228736 (same as parent's).
+  #         Child 1 pid is 228759
+  #         Child 1 process group ID is 228759 (different from parent's).
+  #         true
+  #         true
+  #
+  # *   Less than `-1`: Waits for any child whose process group ID is `-pid`:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #         end
+  #         sleep 1
+  #         retrieved_pid = Process.wait(-child1_pid)
+  #         puts "Process.wait(-child1_pid) returned pid #{retrieved_pid}, which is child 1 pid."
+  #         begin
+  #           Process.wait(-child1_pid)
+  #         rescue Errno::ECHILD => x
+  #           puts "Raised #{x.class}, because there's no longer a child with process group id #{child1_pid}."
+  #         end
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 230083.
+  #         Child 0 pid is 230108
+  #         Child 0 process group ID is 230083 (same as parent's).
+  #         Child 1 pid is 230109
+  #         Child 1 process group ID is 230109 (different from parent's).
+  #         Process.wait(-child1_pid) returned pid 230109, which is child 1 pid.
+  #         Raised Errno::ECHILD, because there's no longer a child with process group id 230109.
+  #
+  # Argument `flags` should be given as one of the following constants, or as the
+  # logical OR of both:
+  #
+  # *   Process::WNOHANG: Does not block if no child process is available.
+  # *   Process::WUNTRACED: May return a stopped child process, even if not yet
+  #     reported.
+  #
+  # Not all flags are available on all platforms.
+  #
+  # Raises Errno::ECHILD if there is no suitable child process.
   #
-  # < -1
-  # :   Waits for any child whose process group ID equals the absolute value of
-  #     *pid*.
-  #
-  #
-  # 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.
-  #
-  # Calling this method raises a SystemCallError if there are no child processes.
   # Not available on all platforms.
   #
-  #     include Process
-  #     fork { exit 99 }                 #=> 27429
-  #     wait                             #=> 27429
-  #     $?.exitstatus                    #=> 99
-  #
-  #     pid = fork { sleep 3 }           #=> 27440
-  #     Time.now                         #=> 2008-03-08 19:56:16 +0900
-  #     waitpid(pid, Process::WNOHANG)   #=> nil
-  #     Time.now                         #=> 2008-03-08 19:56:16 +0900
-  #     waitpid(pid, 0)                  #=> 27440
-  #     Time.now                         #=> 2008-03-08 19:56:19 +0900
+  # Process.waitpid is an alias for Process.wait.
   #
   def self.wait: (?Integer pid, ?Integer flags) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.wait2(pid=-1, flags=0)      -> [pid, status]
-  #   - Process.waitpid2(pid=-1, flags=0)   -> [pid, status]
+  #   - Process.wait2(pid = -1, flags = 0) -> [pid, status]
   # -->
-  # Waits for a child process to exit (see Process::waitpid for exact semantics)
-  # and returns an array containing the process id and the exit status (a
-  # Process::Status object) of that child. Raises a SystemCallError if there are
-  # no child processes.
+  # Like Process.waitpid, but returns an array containing the child process `pid`
+  # and Process::Status `status`:
   #
-  #     Process.fork { exit 99 }   #=> 27437
-  #     pid, status = Process.wait2
-  #     pid                        #=> 27437
-  #     status.exitstatus          #=> 99
+  #     pid = Process.spawn('ruby', '-e', 'exit 13') # => 309581
+  #     Process.wait2(pid)
+  #     # => [309581, #<Process::Status: pid 309581 exit 13>]
+  #
+  # Process.waitpid2 is an alias for Process.wait2.
   #
   def self.wait2: (?Integer pid, ?Integer flags) -> [ Integer, Process::Status ]
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.waitall   -> [ [pid1,status1], ...]
+  #   - Process.waitall -> array
   # -->
-  # Waits for all children, returning an array of *pid*/*status* pairs (where
-  # *status* is a Process::Status object).
-  #
-  #     fork { sleep 0.2; exit 2 }   #=> 27432
-  #     fork { sleep 0.1; exit 1 }   #=> 27433
-  #     fork {            exit 0 }   #=> 27434
-  #     p Process.waitall
+  # Waits for all children, returns an array of 2-element arrays; each subarray
+  # contains the integer pid and Process::Status status for one of the reaped
+  # child processes:
   #
-  # *produces*:
-  #
-  #     [[30982, #<Process::Status: pid 30982 exit 0>],
-  #      [30979, #<Process::Status: pid 30979 exit 1>],
-  #      [30976, #<Process::Status: pid 30976 exit 2>]]
+  #     pid0 = Process.spawn('ruby', '-e', 'exit 13') # => 325470
+  #     pid1 = Process.spawn('ruby', '-e', 'exit 14') # => 325495
+  #     Process.waitall
+  #     # => [[325470, #<Process::Status: pid 325470 exit 13>], [325495, #<Process::Status: pid 325495 exit 14>]]
   #
   def self.waitall: () -> ::Array[[ Integer, Process::Status ]]
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.wait()                     -> integer
-  #   - Process.wait(pid=-1, flags=0)      -> integer
-  #   - Process.waitpid(pid=-1, flags=0)   -> integer
-  # -->
-  # Waits for a child process to exit, returns its process id, and sets `$?` to a
-  # Process::Status object containing information on that process. Which child it
-  # waits on depends on the value of *pid*:
-  #
-  # > 0
-  # :   Waits for the child whose process ID equals *pid*.
-  #
-  # 0
-  # :   Waits for any child whose process group ID equals that of the calling
-  #     process.
-  #
-  # -1
-  # :   Waits for any child process (the default if no *pid* is given).
-  #
-  # < -1
-  # :   Waits for any child whose process group ID equals the absolute value of
-  #     *pid*.
+  #   - Process.wait(pid = -1, flags = 0) -> integer
+  # -->
+  # Waits for a suitable child process to exit, returns its process ID, and sets
+  # `$?` to a Process::Status object containing information on that process. Which
+  # child it waits for depends on the value of the given `pid`:
+  #
+  # *   Positive integer: Waits for the child process whose process ID is `pid`:
+  #
+  #         pid0 = Process.spawn('ruby', '-e', 'exit 13') # => 230866
+  #         pid1 = Process.spawn('ruby', '-e', 'exit 14') # => 230891
+  #         Process.wait(pid0)                            # => 230866
+  #         $?                                            # => #<Process::Status: pid 230866 exit 13>
+  #         Process.wait(pid1)                            # => 230891
+  #         $?                                            # => #<Process::Status: pid 230891 exit 14>
+  #         Process.wait(pid0)                            # Raises Errno::ECHILD
+  #
+  # *   `0`: Waits for any child process whose group ID is the same as that of the
+  #     current process:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #         end
+  #         retrieved_pid = Process.wait(0)
+  #         puts "Process.wait(0) returned pid #{retrieved_pid}, which is child 0 pid."
+  #         begin
+  #           Process.wait(0)
+  #         rescue Errno::ECHILD => x
+  #           puts "Raised #{x.class}, because child 1 process group ID differs from parent process group ID."
+  #         end
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 225764.
+  #         Child 0 pid is 225788
+  #         Child 0 process group ID is 225764 (same as parent's).
+  #         Child 1 pid is 225789
+  #         Child 1 process group ID is 225789 (different from parent's).
+  #         Process.wait(0) returned pid 225788, which is child 0 pid.
+  #         Raised Errno::ECHILD, because child 1 process group ID differs from parent process group ID.
+  #
+  # *   `-1` (default): Waits for any child process:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #           sleep 3 # To force child 1 to exit later than child 0 exit.
+  #         end
+  #         child_pids = [child0_pid, child1_pid]
+  #         retrieved_pid = Process.wait(-1)
+  #         puts child_pids.include?(retrieved_pid)
+  #         retrieved_pid = Process.wait(-1)
+  #         puts child_pids.include?(retrieved_pid)
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 228736.
+  #         Child 0 pid is 228758
+  #         Child 0 process group ID is 228736 (same as parent's).
+  #         Child 1 pid is 228759
+  #         Child 1 process group ID is 228759 (different from parent's).
+  #         true
+  #         true
+  #
+  # *   Less than `-1`: Waits for any child whose process group ID is `-pid`:
+  #
+  #         parent_pgpid = Process.getpgid(Process.pid)
+  #         puts "Parent process group ID is #{parent_pgpid}."
+  #         child0_pid = fork do
+  #           puts "Child 0 pid is #{Process.pid}"
+  #           child0_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 0 process group ID is #{child0_pgid} (same as parent's)."
+  #         end
+  #         child1_pid = fork do
+  #           puts "Child 1 pid is #{Process.pid}"
+  #           Process.setpgid(0, Process.pid)
+  #           child1_pgid = Process.getpgid(Process.pid)
+  #           puts "Child 1 process group ID is #{child1_pgid} (different from parent's)."
+  #         end
+  #         sleep 1
+  #         retrieved_pid = Process.wait(-child1_pid)
+  #         puts "Process.wait(-child1_pid) returned pid #{retrieved_pid}, which is child 1 pid."
+  #         begin
+  #           Process.wait(-child1_pid)
+  #         rescue Errno::ECHILD => x
+  #           puts "Raised #{x.class}, because there's no longer a child with process group id #{child1_pid}."
+  #         end
+  #
+  #     Output:
+  #
+  #         Parent process group ID is 230083.
+  #         Child 0 pid is 230108
+  #         Child 0 process group ID is 230083 (same as parent's).
+  #         Child 1 pid is 230109
+  #         Child 1 process group ID is 230109 (different from parent's).
+  #         Process.wait(-child1_pid) returned pid 230109, which is child 1 pid.
+  #         Raised Errno::ECHILD, because there's no longer a child with process group id 230109.
+  #
+  # Argument `flags` should be given as one of the following constants, or as the
+  # logical OR of both:
+  #
+  # *   Process::WNOHANG: Does not block if no child process is available.
+  # *   Process::WUNTRACED: May return a stopped child process, even if not yet
+  #     reported.
+  #
+  # Not all flags are available on all platforms.
+  #
+  # Raises Errno::ECHILD if there is no suitable child process.
   #
-  #
-  # 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.
-  #
-  # Calling this method raises a SystemCallError if there are no child processes.
   # Not available on all platforms.
   #
-  #     include Process
-  #     fork { exit 99 }                 #=> 27429
-  #     wait                             #=> 27429
-  #     $?.exitstatus                    #=> 99
-  #
-  #     pid = fork { sleep 3 }           #=> 27440
-  #     Time.now                         #=> 2008-03-08 19:56:16 +0900
-  #     waitpid(pid, Process::WNOHANG)   #=> nil
-  #     Time.now                         #=> 2008-03-08 19:56:16 +0900
-  #     waitpid(pid, 0)                  #=> 27440
-  #     Time.now                         #=> 2008-03-08 19:56:19 +0900
+  # Process.waitpid is an alias for Process.wait.
   #
   def self.waitpid: (?Integer pid, ?Integer flags) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.wait2(pid=-1, flags=0)      -> [pid, status]
-  #   - Process.waitpid2(pid=-1, flags=0)   -> [pid, status]
+  #   - Process.wait2(pid = -1, flags = 0) -> [pid, status]
   # -->
-  # Waits for a child process to exit (see Process::waitpid for exact semantics)
-  # and returns an array containing the process id and the exit status (a
-  # Process::Status object) of that child. Raises a SystemCallError if there are
-  # no child processes.
+  # Like Process.waitpid, but returns an array containing the child process `pid`
+  # and Process::Status `status`:
+  #
+  #     pid = Process.spawn('ruby', '-e', 'exit 13') # => 309581
+  #     Process.wait2(pid)
+  #     # => [309581, #<Process::Status: pid 309581 exit 13>]
   #
-  #     Process.fork { exit 99 }   #=> 27437
-  #     pid, status = Process.wait2
-  #     pid                        #=> 27437
-  #     status.exitstatus          #=> 99
+  # Process.waitpid2 is an alias for Process.wait2.
   #
   def self.waitpid2: (?Integer pid, ?Integer flags) -> [ Integer, Process::Status ]
+
+  # <!--
+  #   rdoc-file=process.c
+  #   - Process.warmup    -> true
+  # -->
+  # Notify the Ruby virtual machine that the boot sequence is finished, and that
+  # now is a good time to optimize the application. This is useful for long
+  # running applications.
+  #
+  # This method is expected to be called at the end of the application boot. If
+  # the application is deployed using a pre-forking model, `Process.warmup` should
+  # be called in the original process before the first fork.
+  #
+  # The actual optimizations performed are entirely implementation specific and
+  # may change in the future without notice.
+  #
+  # On CRuby, `Process.warmup`:
+  #
+  # *   Performs a major GC.
+  # *   Compacts the heap.
+  # *   Promotes all surviving objects to the old generation.
+  # *   Precomputes the coderange of all strings.
+  # *   Frees all empty heap pages and increments the allocatable pages counter by
+  #     the number of pages freed.
+  # *   Invoke `malloc_trim` if available to free empty malloc pages.
+  #
+  def self.warmup: () -> bool
 end
 
 # <!-- rdoc-file=process.c -->
@@ -996,6 +1640,14 @@ Process::RLIMIT_NOFILE: Integer
 #
 Process::RLIMIT_NPROC: Integer
 
+# <!-- rdoc-file=process.c -->
+# The maximum number of pseudo-terminals that can be created for the real user
+# ID of the calling process.
+#
+# see the system getrlimit(2) manual for details.
+#
+Process::RLIMIT_NPTS: Integer
+
 # <!-- rdoc-file=process.c -->
 # Specifies the limit (in pages) of the process's resident set.
 #
@@ -1080,14 +1732,15 @@ module Process::GID
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.egid          -> integer
-  #   - Process::GID.eid      -> integer
-  #   - Process::Sys.geteid   -> integer
+  #   - Process.egid        -> integer
+  #   - Process::GID.eid    -> integer
+  #   - Process::Sys.geteid -> integer
   # -->
-  # Returns the effective group ID for this process. Not available on all
-  # platforms.
+  # Returns the effective group ID for the current process:
   #
-  #     Process.egid   #=> 500
+  #     Process.egid # => 500
+  #
+  # Not available on all platforms.
   #
   def self.eid: () -> Integer
 
@@ -1142,13 +1795,13 @@ module Process::GID
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.gid           -> integer
-  #   - Process::GID.rid      -> integer
-  #   - Process::Sys.getgid   -> integer
+  #   - Process.gid         -> integer
+  #   - Process::GID.rid    -> integer
+  #   - Process::Sys.getgid -> integer
   # -->
-  # Returns the (real) group ID for this process.
+  # Returns the (real) group ID for the current process:
   #
-  #     Process.gid   #=> 500
+  #     Process.gid # => 1000
   #
   def self.rid: () -> Integer
 
@@ -1177,188 +1830,192 @@ module Process::GID
 end
 
 # <!-- rdoc-file=process.c -->
-# Process::Status encapsulates the information on the status of a running or
-# terminated system process. The built-in variable `$?` is either `nil` or a
-# Process::Status object.
-#
-#     fork { exit 99 }   #=> 26557
-#     Process.wait       #=> 26557
-#     $?.class           #=> Process::Status
-#     $?.to_i            #=> 25344
-#     $? >> 8            #=> 99
-#     $?.stopped?        #=> false
-#     $?.exited?         #=> true
-#     $?.exitstatus      #=> 99
-#
-# Posix systems record information on processes using a 16-bit integer.  The
-# lower bits record the process status (stopped, exited, signaled) and the upper
-# bits possibly contain additional information (for example the program's return
-# code in the case of exited processes). Pre Ruby 1.8, these bits were exposed
-# directly to the Ruby program. Ruby now encapsulates these in a Process::Status
-# object. To maximize compatibility, however, these objects retain a
-# bit-oriented interface. In the descriptions that follow, when we talk about
-# the integer value of *stat*, we're referring to this 16 bit value.
+# A Process::Status contains information about a system process.
+#
+# Thread-local variable `$?` is initially `nil`. Some methods assign to it a
+# Process::Status object that represents a system process (either running or
+# terminated):
+#
+#     `ruby -e "exit 99"`
+#     stat = $?       # => #<Process::Status: pid 1262862 exit 99>
+#     stat.class      # => Process::Status
+#     stat.to_i       # => 25344
+#     stat.stopped?   # => false
+#     stat.exited?    # => true
+#     stat.exitstatus # => 99
 #
 class Process::Status < Object
   # <!--
   #   rdoc-file=process.c
-  #   - stat & num   -> integer
+  #   - stat & mask -> integer
   # -->
-  # Logical AND of the bits in *stat* with *num*.
+  # This method is deprecated as #to_i value is system-specific; use predicate
+  # methods like #exited? or #stopped?, or getters like #exitstatus or #stopsig.
   #
-  #     fork { exit 0x37 }
-  #     Process.wait
-  #     sprintf('%04x', $?.to_i)       #=> "3700"
-  #     sprintf('%04x', $? & 0x1e00)   #=> "1600"
+  # Returns the logical AND of the value of #to_i with `mask`:
+  #
+  #     `cat /nop`
+  #     stat = $?                 # => #<Process::Status: pid 1155508 exit 1>
+  #     sprintf('%x', stat.to_i)  # => "100"
+  #     stat & 0x00               # => 0
+  #
+  # ArgumentError is raised if `mask` is negative.
   #
   def &: (Integer num) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat == other   -> true or false
+  #   - stat == other -> true or false
   # -->
-  # Returns `true` if the integer value of *stat* equals *other*.
+  # 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
   #
   def ==: (untyped other) -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat >> num   -> integer
+  #   - stat >> places -> integer
   # -->
-  # Shift the bits in *stat* right *num* places.
+  # This method is deprecated as #to_i value is system-specific; use predicate
+  # methods like #exited? or #stopped?, or getters like #exitstatus or #stopsig.
   #
-  #     fork { exit 99 }   #=> 26563
-  #     Process.wait       #=> 26563
-  #     $?.to_i            #=> 25344
-  #     $? >> 8            #=> 99
+  # Returns the value of #to_i, shifted `places` to the right:
+  #
+  #     `cat /nop`
+  #     stat = $?                 # => #<Process::Status: pid 1155508 exit 1>
+  #     stat.to_i                 # => 256
+  #     stat >> 1                 # => 128
+  #     stat >> 2                 # => 64
+  #
+  # ArgumentError is raised if `places` is negative.
   #
   def >>: (Integer num) -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.coredump?   -> true or false
+  #   - coredump? -> true or false
   # -->
-  # Returns `true` if *stat* generated a coredump when it terminated. Not
-  # available on all platforms.
+  # Returns `true` if the process generated a coredump when it terminated, `false`
+  # if not.
+  #
+  # Not available on all platforms.
   #
   def coredump?: () -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.exited?   -> true or false
+  #   - exited? -> true or false
   # -->
-  # Returns `true` if *stat* exited normally (for example using an `exit()` call
-  # or finishing the program).
+  # Returns `true` if the process exited normally (for example using an `exit()`
+  # call or finishing the program), `false` if not.
   #
   def exited?: () -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.exitstatus   -> integer or nil
+  #   - exitstatus -> integer or nil
   # -->
-  # Returns the least significant eight bits of the return code of *stat*. Only
-  # available if #exited? is `true`.
-  #
-  #     fork { }           #=> 26572
-  #     Process.wait       #=> 26572
-  #     $?.exited?         #=> true
-  #     $?.exitstatus      #=> 0
+  # Returns the least significant eight bits of the return code of the process if
+  # it has exited; `nil` otherwise:
   #
-  #     fork { exit 99 }   #=> 26573
-  #     Process.wait       #=> 26573
-  #     $?.exited?         #=> true
-  #     $?.exitstatus      #=> 99
+  #     `exit 99`
+  #     $?.exitstatus # => 99
   #
   def exitstatus: () -> Integer?
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.inspect   -> string
+  #   - inspect -> string
   # -->
-  # Override the inspection method.
+  # Returns a string representation of `self`:
   #
   #     system("false")
-  #     p $?.inspect #=> "#<Process::Status: pid 12861 exit 1>"
+  #     $?.inspect # => "#<Process::Status: pid 1303494 exit 1>"
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.pid   -> integer
+  #   - pid -> integer
   # -->
-  # Returns the process ID that this status object represents.
+  # Returns the process ID of the process:
   #
-  #     fork { exit }   #=> 26569
-  #     Process.wait    #=> 26569
-  #     $?.pid          #=> 26569
+  #     system("false")
+  #     $?.pid # => 1247002
   #
   def pid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.signaled?   -> true or false
+  #   - signaled? -> true or false
   # -->
-  # Returns `true` if *stat* terminated because of an uncaught signal.
+  # Returns `true` if the process terminated because of an uncaught signal,
+  # `false` otherwise.
   #
   def signaled?: () -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.stopped?   -> true or false
+  #   - stopped? -> true or false
   # -->
-  # Returns `true` if this process is stopped. This is only returned if the
-  # corresponding #wait call had the Process::WUNTRACED flag set.
+  # Returns `true` if this process is stopped, and if the corresponding #wait call
+  # had the Process::WUNTRACED flag set, `false` otherwise.
   #
   def stopped?: () -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.stopsig   -> integer or nil
+  #   - stopsig -> integer or nil
   # -->
-  # Returns the number of the signal that caused *stat* to stop (or `nil` if self
-  # is not stopped).
+  # Returns the number of the signal that caused the process to stop, or `nil` if
+  # the process is not stopped.
   #
   def stopsig: () -> Integer?
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.success?   -> true, false or nil
+  #   - success? -> true, false, or nil
   # -->
-  # Returns `true` if *stat* is successful, `false` if not. Returns `nil` if
-  # #exited? is not `true`.
+  # Returns:
+  #
+  # *   `true` if the process has completed successfully and exited.
+  # *   `false` if the process has completed unsuccessfully and exited.
+  # *   `nil` if the process has not exited.
   #
   def success?: () -> bool
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.termsig   -> integer or nil
+  #   - termsig -> integer or nil
   # -->
-  # Returns the number of the signal that caused *stat* to terminate (or `nil` if
-  # self was not terminated by an uncaught signal).
+  # Returns the number of the signal that caused the process to terminate or `nil`
+  # if the process was not terminated by an uncaught signal.
   #
   def termsig: () -> Integer?
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.to_i     -> integer
+  #   - to_i     -> integer
   # -->
-  # Returns the bits in *stat* as an Integer. Poking around in these bits is
-  # platform dependent.
+  # Returns the system-dependent integer status of `self`:
   #
-  #     fork { exit 0xab }         #=> 26566
-  #     Process.wait               #=> 26566
-  #     sprintf('%04x', $?.to_i)   #=> "ab00"
+  #     `cat /nop`
+  #     $?.to_i # => 256
   #
   def to_i: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - stat.to_s   -> string
+  #   - to_s -> string
   # -->
-  # Show pid and exit status as a string.
+  # Returns a string representation of `self`:
   #
-  #     system("false")
-  #     p $?.to_s         #=> "pid 12766 exit 1"
+  #     `cat /nop`
+  #     $?.to_s # => "pid 1262141 exit 1"
   #
   def to_s: () -> String
 end
@@ -1372,37 +2029,37 @@ end
 module Process::Sys
   # <!--
   #   rdoc-file=process.c
-  #   - Process.euid           -> integer
-  #   - Process::UID.eid       -> integer
-  #   - Process::Sys.geteuid   -> integer
+  #   - Process.euid         -> integer
+  #   - Process::UID.eid     -> integer
+  #   - Process::Sys.geteuid -> integer
   # -->
-  # Returns the effective user ID for this process.
+  # Returns the effective user ID for the current process.
   #
-  #     Process.euid   #=> 501
+  #     Process.euid # => 501
   #
   def self.geteuid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.gid           -> integer
-  #   - Process::GID.rid      -> integer
-  #   - Process::Sys.getgid   -> integer
+  #   - Process.gid         -> integer
+  #   - Process::GID.rid    -> integer
+  #   - Process::Sys.getgid -> integer
   # -->
-  # Returns the (real) group ID for this process.
+  # Returns the (real) group ID for the current process:
   #
-  #     Process.gid   #=> 500
+  #     Process.gid # => 1000
   #
   def self.getgid: () -> Integer
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.uid           -> integer
-  #   - Process::UID.rid      -> integer
-  #   - Process::Sys.getuid   -> integer
+  #   - Process.uid         -> integer
+  #   - Process::UID.rid    -> integer
+  #   - Process::Sys.getuid -> integer
   # -->
-  # Returns the (real) user ID of this process.
+  # Returns the (real) user ID of the current process.
   #
-  #     Process.uid   #=> 501
+  #     Process.uid # => 1000
   #
   def self.getuid: () -> Integer
 
@@ -1533,13 +2190,13 @@ module Process::UID
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.euid           -> integer
-  #   - Process::UID.eid       -> integer
-  #   - Process::Sys.geteuid   -> integer
+  #   - Process.euid         -> integer
+  #   - Process::UID.eid     -> integer
+  #   - Process::Sys.geteuid -> integer
   # -->
-  # Returns the effective user ID for this process.
+  # Returns the effective user ID for the current process.
   #
-  #     Process.euid   #=> 501
+  #     Process.euid # => 501
   #
   def self.eid: () -> Integer
 
@@ -1594,13 +2251,13 @@ module Process::UID
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.uid           -> integer
-  #   - Process::UID.rid      -> integer
-  #   - Process::Sys.getuid   -> integer
+  #   - Process.uid         -> integer
+  #   - Process::UID.rid    -> integer
+  #   - Process::Sys.getuid -> integer
   # -->
-  # Returns the (real) user ID of this process.
+  # Returns the (real) user ID of the current process.
   #
-  #     Process.uid   #=> 501
+  #     Process.uid # => 1000
   #
   def self.rid: () -> Integer
 
@@ -1628,6 +2285,9 @@ module Process::UID
   def self.eid=: (Integer user) -> Integer
 end
 
+# <!-- rdoc-file=process.c -->
+# Placeholder for rusage
+#
 class Process::Tms < Struct[Float]
 end