1 files changed, 43 insertions, 0 deletions
diff --git a/lib/rinda/rinda.rb b/lib/rinda/rinda.rb
index 273560b1de..a29d776810 100644
--- a/lib/rinda/rinda.rb
+++ b/lib/rinda/rinda.rb
@@ -1,10 +1,32 @@
+#
+# rinda.rb: A Ruby implementation of the Linda distibuted computing paradigm.
+#
+# <i>Introduction to Linda/rinda?</i>
+#
+# <i>Why is this library separate from <tt>drb</tt>?</i> 
+#
+# <i>Example(s)</i> 
+#
+# (See the samples directory in the Ruby distribution, from 1.8.2 onwards.)
+#
+
 require 'thread'
 
+#
+# A module to implement the Linda programming paradigm in Ruby.
+# This is part of +drb+ (dRuby).
+#
 module Rinda
   class RequestCanceledError < ThreadError; end
   class RequestExpiredError < ThreadError; end
 
+  #
+  # A tuple is the elementary object in Rinda programming.
+  # Tuples may be matched against templates if the tuple and
+  # the template are the same size.
+  #
   class Tuple
+    # Initialize a tuple with an Array or a Hash.
     def initialize(ary_or_hash)
       if Hash === ary_or_hash
 	init_with_hash(ary_or_hash)
@@ -13,14 +35,18 @@ module Rinda
       end
     end
 
+    # The number of elements in the tuple.
     def size
       @tuple.size
     end
 
+    # Accessor method for elements of the tuple.
     def [](k)
       @tuple[k]
     end
 
+    # Iterate through the tuple, yielding the index or key, and the
+    # value, thus ensuring arrays are iterated similarly to hashes.
     def each # FIXME
       if Hash === @tuple
 	@tuple.each { |k, v| yield(k, v) }
@@ -29,6 +55,7 @@ module Rinda
       end
     end
 
+    # Return the tuple itself -- i.e the Array or hash.
     def value
       @tuple
     end
@@ -52,7 +79,13 @@ module Rinda
     end
   end
 
+  #
+  # Templates are used to match tuples in Rinda.
+  #
   class Template < Tuple
+    # Perform the matching of a tuple against a template.  An
+    # element with a +nil+ value in a template acts as a wildcard,
+    # matching any value in the corresponding position in the tuple.
     def match(tuple)
       return false unless tuple.respond_to?(:size)
       return false unless tuple.respond_to?(:[])
@@ -64,11 +97,15 @@ module Rinda
       return true
     end
     
+    # Alias for #match.
     def ===(tuple)
       match(tuple)
     end
   end
   
+  #
+  # <i>Documentation?</i>
+  #
   class DRbObjectTemplate
     def initialize(uri=nil, ref=nil)
       @drb_uri = uri
@@ -87,6 +124,9 @@ module Rinda
     end
   end
 
+  #
+  # TupleSpaceProxy allows a remote Tuplespace to appear as local.
+  #
   class TupleSpaceProxy
     def initialize(ts)
       @ts = ts
@@ -115,6 +155,9 @@ module Rinda
     end
   end
 
+  #
+  # <i>Documentation?</i>
+  #
   class SimpleRenewer
     include DRbUndumped
     def initialize(sec=180)