* lib/drb/drb.rb: Improved documentation by adding or hiding methods.

* lib/drb/eq.rb:  ditto.
* lib/drb/extserv.rb:  ditto.
* lib/drb/gw.rb:  ditto.
* lib/drb/invokemethod.rb:  ditto.
* lib/drb/observer.rb:  ditto.
* lib/drb/ssl.rb:  ditto.
* lib/drb/timeridconv.rb:  ditto.
* lib/drb/unix.rb:  ditto.

* sample/drb/gw_cu.rb:  Fixed bug in DRb gateway sample.


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

9 files changed, 109 insertions, 16 deletions

diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb
index fa914f877d..f5d4a26906 100644
--- a/lib/drb/drb.rb
+++ b/lib/drb/drb.rb
@@ -426,6 +426,8 @@ module DRb
 
   # An exception wrapping an error object
   class DRbRemoteError < DRbError
+
+    # Creates a new remote error that wraps the Exception +error+
     def initialize(error)
       @reason = error.class.to_s
       super("#{error.message} (#{error.class})")
@@ -505,7 +507,16 @@ module DRb
     end
   end
 
+  # An Array wrapper that can be sent to another server via DRb.
+  #
+  # All entries in the array will be dumped or be references that point to
+  # the local server.
+
   class DRbArray
+
+    # Creates a new DRbArray that either dumps or wraps all the items in +ary+
+    # so they can be loaded by a remote DRb server.
+
     def initialize(ary)
       @ary = ary.collect { |obj|
         if obj.kind_of? DRbUndumped
@@ -521,11 +532,11 @@ module DRb
       }
     end
 
-    def self._load(s)
+    def self._load(s) # :nodoc:
       Marshal::load(s)
     end
 
-    def _dump(lv)
+    def _dump(lv) # :nodoc:
       Marshal.dump(@ary)
     end
   end
@@ -629,7 +640,7 @@ module DRb
     end
 
     private
-    def make_proxy(obj, error=false)
+    def make_proxy(obj, error=false) # :nodoc:
       if error
         DRbRemoteError.new(obj)
       else
@@ -793,10 +804,13 @@ module DRb
     module_function :auto_load
   end
 
-  # The default drb protocol.
+  # The default drb protocol which communicates over a TCP socket.
   #
-  # Communicates over a TCP socket.
+  # The DRb TCP protocol URI looks like:
+  # <code>druby://<host>:<port>?<option></code>.  The option is optional.
+
   class DRbTCPSocket
+    # :stopdoc:
     private
     def self.parse_uri(uri)
       if uri =~ /^druby:\/\/(.*?):(\d+)(\?(.*))?$/
@@ -840,6 +854,7 @@ module DRb
       return TCPServer.open('0.0.0.0', port) if families.has_key?('AF_INET')
       return TCPServer.open('::', port) if families.has_key?('AF_INET6')
       return TCPServer.open(port)
+      # :stopdoc:
     end
 
     # Open a server listening for connections at +uri+ using
@@ -1008,6 +1023,8 @@ module DRb
       self.new_with(uri, ref)
     end
 
+    # Creates a new DRbObject from a +uri+ and object +ref+.
+
     def self.new_with(uri, ref)
       it = self.allocate
       it.instance_variable_set(:@uri, uri)
@@ -1058,6 +1075,7 @@ module DRb
     undef :to_s
     undef :to_a if respond_to?(:to_a)
 
+    # Routes respond_to? to the referenced remote object.
     def respond_to?(msg_id, priv=false)
       case msg_id
       when :_dump
@@ -1069,7 +1087,7 @@ module DRb
       end
     end
 
-    # Routes method calls to the referenced object.
+    # Routes method calls to the referenced remote object.
     def method_missing(msg_id, *a, &b)
       if DRb.here?(@uri)
         obj = DRb.to_obj(@ref)
@@ -1094,7 +1112,7 @@ module DRb
       end
     end
 
-    def self.with_friend(uri)
+    def self.with_friend(uri) # :nodoc:
       friend = DRb.fetch_server(uri)
       return yield() unless friend
 
@@ -1105,7 +1123,7 @@ module DRb
       Thread.current['DRb'] = save if friend
     end
 
-    def self.prepare_backtrace(uri, result)
+    def self.prepare_backtrace(uri, result) # :nodoc:
       prefix = "(#{uri}) "
       bt = []
       result.backtrace.each do |x|
@@ -1250,6 +1268,7 @@ module DRb
       @@idconv = idconv
     end
 
+    # Set the default safe level to +level+
     def self.default_safe_level(level)
       @@safe_level = level
     end
@@ -1366,6 +1385,7 @@ module DRb
     # The configuration of this DRbServer
     attr_reader :config
 
+    # The safe level for this server
     attr_reader :safe_level
 
     # Set whether to operate in verbose mode.
@@ -1383,6 +1403,7 @@ module DRb
       @thread.alive?
     end
 
+    # Is +uri+ the URI for this server?
     def here?(uri)
       @exported_uri.include?(uri)
     end
@@ -1737,12 +1758,15 @@ module DRb
   module_function :install_acl
 
   @mutex = Mutex.new
-  def mutex
+  def mutex # :nodoc:
     @mutex
   end
   module_function :mutex
 
   @server = {}
+  # Registers +server+ with DRb.
+  #
+  # If there is no primary server then +server+ becomes the primary server.
   def regist_server(server)
     @server[server.uri] = server
     mutex.synchronize do
@@ -1751,11 +1775,13 @@ module DRb
   end
   module_function :regist_server
 
+  # Removes +server+ from the list of servers.
   def remove_server(server)
     @server.delete(server.uri)
   end
   module_function :remove_server
 
+  # Retrieves the server with the given +uri+.
   def fetch_server(uri)
     @server[uri]
   end
diff --git a/lib/drb/eq.rb b/lib/drb/eq.rb
index 6328c81202..553f30c598 100644
--- a/lib/drb/eq.rb
+++ b/lib/drb/eq.rb
@@ -1,5 +1,5 @@
 module DRb
-  class DRbObject
+  class DRbObject # :nodoc:
     def ==(other)
       return false unless DRbObject === other
      (@ref == other.__drbref) && (@uri == other.__drburi)
diff --git a/lib/drb/extserv.rb b/lib/drb/extserv.rb
index bb11211cd1..c70ced877c 100644
--- a/lib/drb/extserv.rb
+++ b/lib/drb/extserv.rb
@@ -42,6 +42,8 @@ module DRb
   end
 end
 
+# :stopdoc:
+
 if __FILE__ == $0
   class Foo
     include DRbUndumped
diff --git a/lib/drb/gw.rb b/lib/drb/gw.rb
index b7a5f5383f..b3568ab08d 100644
--- a/lib/drb/gw.rb
+++ b/lib/drb/gw.rb
@@ -2,8 +2,36 @@ require 'drb/drb'
 require 'monitor'
 
 module DRb
+
+  # Gateway id conversion forms a gateway between different DRb protocols or
+  # networks.
+  #
+  # The gateway needs to install this id conversion and create servers for
+  # each of the protocols or networks it will be a gateway between.  It then
+  # needs to create a server that attaches to each of these networks.  For
+  # example:
+  #
+  #   require 'drb/drb'
+  #   require 'drb/unix'
+  #   require 'drb/gw'
+  #
+  #   DRb.install_id_conv DRb::GWIdConv.new
+  #   gw = DRb::GW.new
+  #   s1 = DRb::DRbServer.new 'drbunix:/path/to/gateway', gw
+  #   s2 = DRb::DRbServer.new 'druby://example:10000', gw
+  #
+  #   s1.thread.join
+  #   s2.thread.join
+  #
+  # Each client must register services with the gateway, for example:
+  #
+  #   DRb.start_service 'drbunix:', nil # an anonymous server
+  #   gw = DRbObject.new nil, 'drbunix:/path/to/gateway'
+  #   gw[:unix] = some_service
+  #   DRb.thread.join
+
   class GWIdConv < DRbIdConv
-    def to_obj(ref)
+    def to_obj(ref) # :nodoc:
       if Array === ref && ref[0] == :DRbObject
         return DRbObject.new_with(ref[1], ref[2])
       end
@@ -11,19 +39,29 @@ module DRb
     end
   end
 
+  # The GW provides a synchronized store for participants in the gateway to
+  # communicate.
+
   class GW
     include MonitorMixin
+
+    # Creates a new GW
+
     def initialize
       super()
       @hash = {}
     end
 
+    # Retrieves +key+ from the GW
+
     def [](key)
       synchronize do
         @hash[key]
       end
     end
 
+    # Stores value +v+ at +key+ in the GW
+
     def []=(key, v)
       synchronize do
         @hash[key] = v
@@ -31,7 +69,7 @@ module DRb
     end
   end
 
-  class DRbObject
+  class DRbObject # :nodoc:
     def self._load(s)
       uri, ref = Marshal.load(s)
       if DRb.uri == uri
diff --git a/lib/drb/invokemethod.rb b/lib/drb/invokemethod.rb
index 353dbd00d8..d11feabcb8 100644
--- a/lib/drb/invokemethod.rb
+++ b/lib/drb/invokemethod.rb
@@ -2,7 +2,7 @@
 
 module DRb
   class DRbServer
-    module InvokeMethod18Mixin
+    module InvokeMethod18Mixin # :nodoc: all
       def block_yield(x)
         if x.size == 1 && x[0].class == Array
           x[0] = DRbArray.new(x[0])
diff --git a/lib/drb/observer.rb b/lib/drb/observer.rb
index 149426db7b..cab9ebc60b 100644
--- a/lib/drb/observer.rb
+++ b/lib/drb/observer.rb
@@ -1,9 +1,12 @@
 require 'observer'
 
 module DRb
+  # The Observable module extended to DRb.  See Observable for details.
   module DRbObservable
     include Observable
 
+    # Notifies observers of a change in state.  See also
+    # Observable#notify_observers
     def notify_observers(*arg)
       if defined? @observer_state and @observer_state
         if defined? @observer_peers
diff --git a/lib/drb/ssl.rb b/lib/drb/ssl.rb
index c4f76987de..c0dd9c49f4 100644
--- a/lib/drb/ssl.rb
+++ b/lib/drb/ssl.rb
@@ -5,8 +5,13 @@ require 'singleton'
 
 module DRb
 
+  # The protocol for DRb over an SSL socket
+  #
+  # The URI for a DRb socket over SSL is:
+  # <code>drbssl://<host>:<port>?<option></code>.  The option is optional
   class DRbSSLSocket < DRbTCPSocket
 
+    # :stopdoc:
     class SSLConfig
 
       DEFAULT = {
@@ -190,6 +195,8 @@ module DRb
         retry
       end
     end
+
+    # :stopdoc:
   end
 
   DRbProtocol.add_protocol(DRbSSLSocket)
diff --git a/lib/drb/timeridconv.rb b/lib/drb/timeridconv.rb
index b460e2c987..4ea3035f39 100644
--- a/lib/drb/timeridconv.rb
+++ b/lib/drb/timeridconv.rb
@@ -2,8 +2,17 @@ require 'drb/drb'
 require 'monitor'
 
 module DRb
+
+  # Timer id conversion keeps objects alive for a certain amount of time after
+  # their last access.  The default time period is 600 seconds and can be
+  # changed upon initialization.
+  #
+  # To use TimerIdConv:
+  #
+  #  DRb.install_id_conv TimerIdConv.new 60 # one minute
+
   class TimerIdConv < DRbIdConv
-    class TimerHolder2
+    class TimerHolder2 # :nodoc:
       include MonitorMixin
 
       class InvalidIndexError < RuntimeError; end
@@ -71,18 +80,19 @@ module DRb
       end
     end
 
+    # Creates a new TimerIdConv which will hold objects for +timeout+ seconds.
     def initialize(timeout=600)
       @holder = TimerHolder2.new(timeout)
     end
 
-    def to_obj(ref)
+    def to_obj(ref) # :nodoc:
       return super if ref.nil?
       @holder.fetch(ref)
     rescue TimerHolder2::InvalidIndexError
       raise "invalid reference"
     end
 
-    def to_id(obj)
+    def to_id(obj) # :nodoc:
       return @holder.add(obj)
     end
   end
diff --git a/lib/drb/unix.rb b/lib/drb/unix.rb
index 6de5052451..4d245780a5 100644
--- a/lib/drb/unix.rb
+++ b/lib/drb/unix.rb
@@ -6,7 +6,13 @@ raise(LoadError, "UNIXServer is required") unless defined?(UNIXServer)
 
 module DRb
 
+  # Implements DRb over a UNIX socket
+  #
+  # DRb UNIX socket URIs look like <code>drbunix:<path>?<option></code>.  The
+  # option is optional.
+
   class DRbUNIXSocket < DRbTCPSocket
+    # :stopdoc:
     def self.parse_uri(uri)
       if /^drbunix:(.*?)(\?(.*))?$/ =~ uri
         filename = $1
@@ -105,4 +111,5 @@ module DRb
   end
 
   DRbProtocol.add_protocol(DRbUNIXSocket)
+  # :startdoc:
 end