From: Hugh Sasse <hgs@...>
Date: 2006-07-18T02:09:48+09:00
Subject: tuplespace - make comments visible to rdoc.

comments in rdoc conventionally don't start with two # marks and don't
have a blank line before the thing (class, method) they document.  
This patch against

-rw-r--r--   1 hgs      staff    4467350 Jul 17 17:39 stable-snapshot.tar.gz
md5sum: d4afdc6b4b827e269a2eac9f7aa7f434  stable-snapshot.tar.gz

attempts to fix this. Only the comment <I>Documentation?</i> before
WaitTemplateEntry has not been processed this way, as it doesn't add
anything at the moment.

        HTH
        Hugh

--- ./lib/rinda/tuplespace.rb.orig	2005-10-24 16:31:30.000000000 +0100
+++ ./lib/rinda/tuplespace.rb	2006-07-17 17:58:10.839431000 +0100
@@ -5,23 +5,23 @@
 
 module Rinda
 
-  ##
+  #
   # A TupleEntry is a Tuple (i.e. a possible entry in some Tuplespace)
   # together with expiry and cancellation data.
-
+  #
   class TupleEntry
 
     include DRbUndumped
 
     attr_accessor :expires
 
-    ##
+    #
     # Creates a TupleEntry based on +ary+ with an optional renewer or expiry
     # time +sec+.
     #
     # A renewer must implement the +renew+ method which returns a Numeric,
     # nil, or true to indicate when the tuple has expired.
-
+    #
     def initialize(ary, sec=nil)
       @cancel = false
       @expires = nil
@@ -30,37 +30,37 @@
       renew(sec)
     end
 
-    ##
+    #
     # Marks this TupleEntry as canceled.
-
+    #
     def cancel
       @cancel = true
     end
 
-    ##
+    #
     # A TupleEntry is dead when it is canceled or expired.
-
+    #
     def alive?
       !canceled? && !expired?
     end
 
-    ##
+    #
     # Return the object which makes up the tuple itself: the Array
     # or Hash.
-
+    #
     def value; @tuple.value; end
 
-    ##
+    #
     # Returns the canceled status.
-
+    #
     def canceled?; @cancel; end
 
-    ##
+    #
     # Has this tuple expired? (true/false).
     #
     # A tuple has expired when its expiry timer based on the +sec+ argument to
     # #initialize runs out.
-
+    #
     def expired?
       return true unless @expires
       return false if @expires > Time.now
@@ -70,7 +70,7 @@
       return @expires < Time.now
     end
 
-    ##
+    #
     # Reset the expiry time according to +sec_or_renewer+.  
     #
     # +nil+::    it is set to expire in the far future.
@@ -79,19 +79,19 @@
     #
     # Otherwise the argument refers to some kind of renewer object
     # which will reset its expiry time. 
-
+    #
     def renew(sec_or_renewer)
       sec, @renewer = get_renewer(sec_or_renewer)
       @expires = make_expires(sec)
     end
 
-    ##
+    #
     # Returns an expiry Time based on +sec+ which can be one of:
     # Numeric:: +sec+ seconds into the future
     # +true+::  the expiry time is the start of 1970 (i.e. expired)
     # +nil+::   it is  Tue Jan 19 03:14:07 GMT Standard Time 2038 (i.e. when
     #           UNIX clocks will die)
-
+    #
     def make_expires(sec=nil)
       case sec
       when Numeric
@@ -103,43 +103,43 @@
       end
     end
 
-    ##
+    #
     # Retrieves +key+ from the tuple.
-
+    #
     def [](key)
       @tuple[key]
     end
 
-    ##
+    #
     # Fetches +key+ from the tuple.
-
+    #
     def fetch(key)
       @tuple.fetch(key)
     end
 
-    ##
+    #
     # The size of the tuple.
-
+    #
     def size
       @tuple.size
     end
 
-    ##
+    #
     # Creates a Rinda::Tuple for +ary+.
-
+    #
     def make_tuple(ary)
       Rinda::Tuple.new(ary)
     end
 
     private
 
-    ##
+    #
     # Returns a valid argument to make_expires and the renewer or nil.
     #
     # Given +true+, +nil+, or Numeric, returns that value and +nil+ (no actual
     # renewer).  Otherwise it returns an expiry value from calling +it.renew+
     # and the renewer.
-
+    #
     def get_renewer(it)
       case it
       when Numeric, true, nil
@@ -155,14 +155,14 @@
 
   end
 
-  ##
+  #
   # A TemplateEntry is a Template together with expiry and cancellation data.
-
+  #
   class TemplateEntry < TupleEntry
-    ##
+    #
     # Matches this TemplateEntry against +tuple+.  See Template#match for
     # details on how a Template matches a Tuple.
-
+    #
     def match(tuple)
       @tuple.match(tuple)
     end
@@ -175,7 +175,7 @@
 
   end
 
-  ##
+  #
   # <i>Documentation?</i>
 
   class WaitTemplateEntry < TemplateEntry
@@ -211,7 +211,7 @@
 
   end
 
-  ##
+  #
   # A NotifyTemplateEntry is returned by TupleSpace#notify and is notified of
   # TupleSpace changes.  You may receive either your subscribed event or the
   # 'close' event when iterating over notifications.
@@ -237,10 +237,10 @@
 
   class NotifyTemplateEntry < TemplateEntry
 
-    ##
+    #
     # Creates a new NotifyTemplateEntry that watches +place+ for +event+s that
     # match +tuple+.
-
+    #
     def initialize(place, event, tuple, expires=nil)
       ary = [event, Rinda::Template.new(tuple)]
       super(ary, expires)
@@ -248,17 +248,17 @@
       @done = false
     end
 
-    ##
+    #
     # Called by TupleSpace to notify this NotifyTemplateEntry of a new event.
-
+    #
     def notify(ev)
       @queue.push(ev)
     end
 
-    ##
+    #
     # Retrieves a notification.  Raises RequestExpiredError when this
     # NotifyTemplateEntry expires.
-
+    #
     def pop
       raise RequestExpiredError if @done
       it = @queue.pop
@@ -266,9 +266,9 @@
       return it
     end
 
-    ##
+    #
     # Yields event/tuple pairs until this NotifyTemplateEntry expires.
-
+    #
     def each # :yields: event, tuple
       while !@done
         it = pop
@@ -281,19 +281,19 @@
 
   end
 
-  ##
+  #
   # TupleBag is an unordered collection of tuples. It is the basis
   # of Tuplespace.
-
+  #
   class TupleBag
 
     def initialize # :nodoc:
       @hash = {}
     end
 
-    ##
+    #
     # +true+ if the TupleBag to see if it has any expired entries.
-
+    #
     def has_expires?
       @hash.each do |k, v|
         v.each do |tuple|
@@ -303,55 +303,55 @@
       false
     end
 
-    ##
+    #
     # Add +ary+ to the TupleBag.
-
+    #
     def push(ary)
       size = ary.size
       @hash[size] ||= []
       @hash[size].push(ary)
     end
 
-    ##
+    #
     # Removes +ary+ from the TupleBag.
-
+    #
     def delete(ary)
       size = ary.size
       @hash.fetch(size, []).delete(ary)
     end
 
-    ##
+    #
     # Finds all live tuples that match +template+.
-
+    #
     def find_all(template)
       @hash.fetch(template.size, []).find_all do |tuple|
         tuple.alive? && template.match(tuple)
       end
     end
 
-    ##
+    #
     # Finds a live tuple that matches +template+.
-
+    #
     def find(template)
       @hash.fetch(template.size, []).find do |tuple|
         tuple.alive? && template.match(tuple)
       end
     end
 
-    ##
+    #
     # Finds all tuples in the TupleBag which when treated as templates, match
     # +tuple+ and are alive.
-
+    #
     def find_all_template(tuple)
       @hash.fetch(tuple.size, []).find_all do |template|
         template.alive? && template.match(tuple)
       end
     end
 
-    ##
+    #
     # Delete tuples which dead tuples from the TupleBag, returning the deleted
     # tuples.
-
+    #
     def delete_unless_alive
       deleted = []
       @hash.keys.each do |size|
@@ -370,7 +370,7 @@
 
   end
 
-  ##
+  #
   # The Tuplespace manages access to the tuples it contains,
   # ensuring mutual exclusion requirements are met.
   #
@@ -382,13 +382,13 @@
     include DRbUndumped
     include MonitorMixin
 
-    ##
+    #
     # Creates a new TupleSpace.  +period+ is used to control how often to look
     # for dead tuples after modifications to the TupleSpace.
     #
     # If no dead tuples are found +period+ seconds after the last
     # modification, the TupleSpace will stop looking for dead tuples.
-
+    #
     def initialize(period=60)
       super()
       @bag = TupleBag.new
@@ -399,9 +399,9 @@
       @keeper = nil
     end
 
-    ##
+    #
     # Adds +tuple+
-
+    #
     def write(tuple, sec=nil)
       entry = TupleEntry.new(tuple, sec)
       start_keeper
@@ -426,16 +426,16 @@
       entry
     end
 
-    ##
+    #
     # Removes +tuple+
-
+    #
     def take(tuple, sec=nil, &block)
       move(nil, tuple, sec, &block)
     end
 
-    ##
+    #
     # Moves +tuple+ to +port+.
-
+    #
     def move(port, tuple, sec=nil)
       template = WaitTemplateEntry.new(self, tuple, sec)
       yield(template) if block_given?
@@ -470,9 +470,9 @@
       end
     end
 
-    ##
+    #
     # Reads +tuple+, but does not remove it.
-
+    #
     def read(tuple, sec=nil)
       template = WaitTemplateEntry.new(self, tuple, sec)
       yield(template) if block_given?
@@ -494,9 +494,9 @@
       end
     end
 
-    ##
+    #
     # Returns all tuples matching +tuple+.  Does not remove the found tuples.
-
+    #
     def read_all(tuple)
       template = WaitTemplateEntry.new(self, tuple, nil)
       synchronize do
@@ -507,7 +507,7 @@
       end
     end
 
-    ##
+    #
     # Registers for notifications of +event+.  Returns a NotifyTemplateEntry.
     # See NotifyTemplateEntry for examples of how to listen for notifications.
     #
@@ -518,7 +518,7 @@
     #
     # The TupleSpace will also notify you of the 'close' event when the
     # NotifyTemplateEntry has expired.
-
+    #
     def notify(event, tuple, sec=nil)
       template = NotifyTemplateEntry.new(self, event, tuple, sec)
       synchronize do
@@ -529,9 +529,9 @@
 
     private
 
-    ##
+    #
     # Removes dead tuples.
-
+    #
     def keep_clean
       synchronize do
         @read_waiter.delete_unless_alive.each do |e|
@@ -549,10 +549,10 @@
       end
     end
 
-    ##
+    #
     # Notifies all registered listeners for +event+ of a status change of
     # +tuple+.
-
+    #
     def notify_event(event, tuple)
       ev = [event, tuple]
       @notify_waiter.find_all_template(ev).each do |template|
@@ -560,9 +560,9 @@
       end
     end
 
-    ##
+    #
     # Creates a thread that scans the tuplespace for expired tuples.
-
+    #
     def start_keeper
       return if @keeper && @keeper.alive?
       @keeper = Thread.new do
@@ -573,9 +573,9 @@
       end
     end
 
-    ##
+    #
     # Checks the tuplespace to see if it needs cleaning.
-
+    #
     def need_keeper?
       return true if @bag.has_expires?
       return true if @read_waiter.has_expires?