1 files changed, 31 insertions, 21 deletions

diff --git a/lib/timeout.rb b/lib/timeout.rb
index 7e3ee81ed0..36811a1040 100644
--- a/lib/timeout.rb
+++ b/lib/timeout.rb
@@ -1,38 +1,39 @@
+# = timeout.rb
 #
-# timeout.rb -- execution timeout
+# execution timeout
 #
-# Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
-# Copyright (C) 2000  Information-technology Promotion Agency, Japan
-#
-#= SYNOPSIS
+# = Synopsis
 #
 #   require 'timeout'
-#   status = timeout(5) {
-#     # something may take time
+#   status = Timeout::timeout(5) {
+#     # Something that should be interrupted if it takes too much time...
 #   }
 #
-#= DESCRIPTION
-#
-# timeout executes the block.  If the block execution terminates successfully
-# before timeout, it returns true.  If not, it terminates the execution and
-# raise TimeoutError exception.
-#
-#== Parameters
-#
-#  : timout
+# = Description
 #
-#    The time in seconds to wait for block termination.   
+# A way of performing a potentially long-running operation in a thread, and terminating
+# it's execution if it hasn't finished by a fixed amount of time.
 #
-#  : [exception]
+# Previous versions of timeout didn't provide use a module for namespace. This version
+# provides both Timeout.timeout, and a backwards-compatible #timeout.
 #
-#    The exception class to be raised on timeout.
+# = Copyright
 #
-#=end
+# Copyright:: (C) 2000  Network Applied Communication Laboratory, Inc.
+# Copyright:: (C) 2000  Information-technology Promotion Agency, Japan
 
 module Timeout
+  # Raised by Timeout#timeout when the block times out.
   class Error<Interrupt
   end
 
+  # Executes the method's block. If the block execution terminates before +sec+
+  # seconds has passed, it returns true. If not, it terminates the execution
+  # and raises +exception+ (which defaults to Timeout::Error).
+  #
+  # 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 a module method,
+  # so you can call it directly as Timeout.timeout().
   def timeout(sec, exception=Error)
     return yield if sec == nil or sec.zero?
     raise ThreadError, "timeout within critical session" if Thread.critical
@@ -48,13 +49,22 @@ module Timeout
       y.kill if y and y.alive?
     end
   end
+
   module_function :timeout
 end
 
-# compatible
+# Identical to:
+#
+#   Timeout::timeout(n, e, &block).
+#
+# Defined for backwards compatibility with earlier versions of timeout.rb, see
+# Timeout#timeout.
 def timeout(n, e=Timeout::Error, &block)
   Timeout::timeout(n, e, &block)
 end
+
+# Another name for Timeout::Error, defined for backwards compatibility with
+# earlier versions of timeout.rb.
 TimeoutError = Timeout::Error
 
 if __FILE__ == $0