From c86e598b972ba279b28a5d77e571a9559e77d5d1 Mon Sep 17 00:00:00 2001
From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com>
Date: Fri, 16 Jan 2026 10:42:22 +0900
Subject: [PATCH] Improve Timeout.timeout documentation formatting and typos
This commit makes a few minor improvements to the documentation of the `Timeout.timeout` method.
The changes include fixing typos and enhancing formatting for better readability.
We can see the latest version of the documentation here:
https://docs.ruby-lang.org/en/master/Timeout.html#method-c-timeout
Also, we can verify this change locally by running:
```shell
rdoc
open doc/Timeout.html
```
---
lib/timeout.rb | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/lib/timeout.rb b/lib/timeout.rb
index 5d1f61d..e293e3b 100644
--- a/lib/timeout.rb
+++ b/lib/timeout.rb
@@ -212,17 +212,17 @@ def self.synchronize(mutex, &block)
# value of 0 or +nil+ will execute the block without any timeout.
# Any negative number will raise an ArgumentError.
# +klass+:: Exception Class to raise if the block fails to terminate
- # in +sec+ seconds. Omitting will use the default, Timeout::Error
+ # in +sec+ seconds. Omitting will use the default, Timeout::Error.
# +message+:: Error message to raise with Exception Class.
- # Omitting will use the default, "execution expired"
+ # Omitting will use the default, "execution expired".
#
# Returns the result of the block *if* the block completed before
# +sec+ seconds, otherwise raises an exception, based on the value of +klass+.
#
# The exception raised to terminate the given block is the given +klass+, or
# Timeout::ExitException if +klass+ is not given. The reason for that behavior
- # is that Timeout::Error inherits from RuntimeError and might be caught unexpectedly by `rescue`.
- # Timeout::ExitException inherits from Exception so it will only be rescued by `rescue Exception`.
+ # is that Timeout::Error inherits from RuntimeError and might be caught unexpectedly by +rescue+.
+ # Timeout::ExitException inherits from Exception so it will only be rescued by rescue Exception.
# Note that the Timeout::ExitException is translated to a Timeout::Error once it reaches the Timeout.timeout call,
# so outside that call it will be a Timeout::Error.
#
@@ -231,7 +231,7 @@ def self.synchronize(mutex, &block)
# For those reasons, this method cannot be relied on to enforce timeouts for untrusted blocks.
#
# If a scheduler is defined, it will be used to handle the timeout by invoking
- # Scheduler#timeout_after.
+ # Fiber::Scheduler#timeout_after.
#
# Note that this is both a method of module Timeout, so you can include
# Timeout into your classes so they have a #timeout method, as well as
@@ -239,13 +239,13 @@ def self.synchronize(mutex, &block)
#
# ==== Ensuring the exception does not fire inside ensure blocks
#
- # When using Timeout.timeout it can be desirable to ensure the timeout exception does not fire inside an +ensure+ block.
- # The simplest and best way to do so it to put the Timeout.timeout call inside the body of the begin/ensure/end:
+ # When using Timeout.timeout, it can be desirable to ensure the timeout exception does not fire inside an +ensure+ block.
+ # The simplest and best way to do so is to put the Timeout.timeout call inside the body of the +begin+/+ensure+/+end+:
#
# begin
# Timeout.timeout(sec) { some_long_operation }
# ensure
- # cleanup # safe, cannot be interrupt by timeout
+ # cleanup # safe, cannot be interrupted by timeout
# end
#
# If that is not feasible, e.g. if there are +ensure+ blocks inside +some_long_operation+,
@@ -263,17 +263,17 @@ def self.synchronize(mutex, &block)
# end
# }
#
- # An important thing to note is the need to pass an exception klass to Timeout.timeout,
- # otherwise it does not work. Specifically, using +Thread.handle_interrupt(Timeout::ExitException => ...)+
+ # An important thing to note is the need to pass an exception +klass+ to Timeout.timeout,
+ # otherwise it does not work. Specifically, using Thread.handle_interrupt(Timeout::ExitException => ...)
# is unsupported and causes subtle errors like raising the wrong exception outside the block, do not use that.
#
# Note that Thread.handle_interrupt is somewhat dangerous because if setup or cleanup hangs
# then the current thread will hang too and the timeout will never fire.
# Also note the block might run for longer than +sec+ seconds:
- # e.g. some_long_operation executes for +sec+ seconds + whatever time cleanup takes.
+ # e.g. +some_long_operation+ executes for +sec+ seconds + whatever time cleanup takes.
#
- # If you want the timeout to only happen on blocking operations one can use :on_blocking
- # instead of :immediate. However, that means if the block uses no blocking operations after +sec+ seconds,
+ # If you want the timeout to only happen on blocking operations, one can use +:on_blocking+
+ # instead of +:immediate+. However, that means if the block uses no blocking operations after +sec+ seconds,
# the block will not be interrupted.
def self.timeout(sec, klass = nil, message = nil, &block) #:yield: +sec+
return yield(sec) if sec == nil or sec.zero?