Added RDoc comments. See comments at EOF for TODOs.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@3354 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/thwait.rb

@@ -39,6 +39,18 @@
 require "thread.rb"
 require "e2mmap.rb"
 
+#
+# This class watches for termination of multiple threads.  Basic functionality
+# (wait until specified threads have terminated) can be accessed through the
+# class method ThreadsWait::all_waits.  Finer control can be gained using
+# instance methods.
+#
+# Example:
+#
+#   ThreadsWait.all_wait(thr1, thr2, ...) do |t|
+#     STDERR.puts "Thread #{t} has terminated."
+#   end
+#
 class ThreadsWait
   RCS_ID='-$Id: thwait.rb,v 1.3 1998/06/26 03:19:34 keiju Exp keiju $-'
   
@@ -46,7 +58,11 @@ class ThreadsWait
   def_exception("ErrNoWaitingThread", "No threads for waiting.")
   def_exception("ErrNoFinishedThread", "No finished threads.")
   
-  def ThreadsWait.all_waits(*threads)
+  #
+  # Waits until all specified threads have terminated.  If a block is provided,
+  # it is executed for each thread termination.
+  #
+  def ThreadsWait.all_waits(*threads) # :yield: thread
     tw = ThreadsWait.new(*threads)
     if block_given?
       tw.all_waits do |th|
@@ -57,43 +73,45 @@ class ThreadsWait
     end
   end
   
+  #
+  # Creates a ThreadsWait object, specifying the threads to wait on.
+  # Non-blocking.
+  #
   def initialize(*threads)
     @threads = []
     @wait_queue = Queue.new
     join_nowait(*threads) unless threads.empty?
   end
   
-  # accessing
-  #	threads - list threads to be synchronized
+  # Returns the array of threads in the wait queue.
   attr :threads
   
-  # testing
-  #	empty?
-  #	finished?
-
-  # is there any thread to be synchronized.
+  #
+  # Returns true if there are no threads to be synchronized.
+  #
   def empty?
     @threads.empty?
   end
   
-  # is there already terminated thread.
+  #
+  # Returns true if any thread has terminated.
+  #
   def finished?
     !@wait_queue.empty?
   end
   
-  # main process:
-  #	join
-  #	join_nowait
-  #	next_wait
-  #	all_wait
-  
-  # adds thread(s) to join,  waits for any of waiting threads to terminate.
+  #
+  # Waits for specified threads to terminate.
+  #
   def join(*threads)
     join_nowait(*threads)
     next_wait
   end
   
-  # adds thread(s) to join, no wait.
+  #
+  # Specifies the threads that this object will wait for, but does not actually
+  # wait.
+  #
   def join_nowait(*threads)
     threads.flatten!
     @threads.concat threads
@@ -105,10 +123,13 @@ class ThreadsWait
     end
   end
   
-  # waits for any of waiting threads to terminate
-  # if there is no thread to wait, raises ErrNoWaitingThread.
-  # if `nonblock' is true, and there is no terminated thread,
-  # raises ErrNoFinishedThread.
+  #
+  # Waits until any of the specified threads has terminated, and returns the one
+  # that does.
+  #
+  # If there is no thread to wait, raises +ErrNoWaitingThread+.  If +nonblock+
+  # is true, and there is no terminated thread, raises +ErrNoFinishedThread+.
+  #
   def next_wait(nonblock = nil)
     ThreadsWait.fail ErrNoWaitingThread if @threads.empty?
     begin
@@ -119,9 +140,12 @@ class ThreadsWait
     end
   end
   
-  # waits until all of specified threads are terminated.
-  # if a block is supplied for the method, evaluates it for
-  # each thread termination.
+  #
+  # Waits until all of the specified threads are terminated.  If a block is
+  # supplied for the method, it is executed for each thread termination.
+  #
+  # Raises exceptions in the same manner as +next_wait+.
+  #
   def all_waits
     until @threads.empty?
       th = next_wait
@@ -131,3 +155,12 @@ class ThreadsWait
 end
 
 ThWait = ThreadsWait
+
+
+# Documentation comments:
+#  - Source of doumentation is evenly split between Nutshell, existing
+#    comments, and my own rephrasing.
+#  - I'm not particularly confident that the comments are all exactly correct.
+#  - The history, etc., up the top appears in the RDoc output.  Perhaps it would
+#    be better to direct that not to appear, and put something else there
+#    instead.