1 files changed, 46 insertions, 11 deletions

diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb
index f5d4a26906..1d3c413e0c 100644
--- a/lib/drb/drb.rb
+++ b/lib/drb/drb.rb
@@ -514,8 +514,8 @@ module DRb
 
   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.
+    # Creates a new DRbArray that either dumps or wraps all the items in the
+    # Array +ary+ so they can be loaded by a remote DRb server.
 
     def initialize(ary)
       @ary = ary.collect { |obj|
@@ -826,7 +826,12 @@ module DRb
 
     public
 
-    # Open a client connection to +uri+ using configuration +config+.
+    # Open a client connection to +uri+ (DRb URI string) using configuration
+    # +config+.
+    #
+    # This can raise DRb::DRbBadScheme or DRb::DRbBadURI if +uri+ is not for a
+    # recognized protocol.  See DRb::DRbServer.new for information on built-in
+    # URI protocols.
     def self.open(uri, config)
       host, port, = parse_uri(uri)
       host.untaint
@@ -835,6 +840,7 @@ module DRb
       self.new(uri, soc, config)
     end
 
+    # Returns the hostname of this server
     def self.getservername
       host = Socket::gethostname
       begin
@@ -844,6 +850,9 @@ module DRb
       end
     end
 
+    # For the families available for +host+, returns a TCPServer on +port+.
+    # If +port+ is 0 the first available port is used.  IPv4 servers are
+    # preferred over IPv6 servers.
     def self.open_server_inaddr_any(host, port)
       infos = Socket::getaddrinfo(host, nil,
                                   Socket::AF_UNSPEC,
@@ -1023,7 +1032,8 @@ module DRb
       self.new_with(uri, ref)
     end
 
-    # Creates a new DRbObject from a +uri+ and object +ref+.
+    # Creates a DRb::DRbObject given the reference information to the remote
+    # host +uri+ and object +ref+.
 
     def self.new_with(uri, ref)
       it = self.allocate
@@ -1112,6 +1122,7 @@ module DRb
       end
     end
 
+    # Given the +uri+ of another host executes the block provided.
     def self.with_friend(uri) # :nodoc:
       friend = DRb.fetch_server(uri)
       return yield() unless friend
@@ -1123,6 +1134,8 @@ module DRb
       Thread.current['DRb'] = save if friend
     end
 
+    # Returns a modified backtrace from +result+ with the +uri+ where each call
+    # in the backtrace came from.
     def self.prepare_backtrace(uri, result) # :nodoc:
       prefix = "(#{uri}) "
       bt = []
@@ -1254,9 +1267,9 @@ module DRb
       @@load_limit = sz
     end
 
-    # Set the default value for the :acl option.
+    # Set the default access control list to +acl+.  The default ACL is +nil+.
     #
-    # See #new().  The initial default value is nil.
+    # See also DRb::ACL and #new()
     def self.default_acl(acl)
       @@acl = acl
     end
@@ -1268,7 +1281,9 @@ module DRb
       @@idconv = idconv
     end
 
-    # Set the default safe level to +level+
+    # Set the default safe level to +level+.  The default safe level is 0
+    #
+    # See #new for more information.
     def self.default_safe_level(level)
       @@safe_level = level
     end
@@ -1326,6 +1341,9 @@ module DRb
     # :argc_limit :: the maximum number of arguments to a remote
     #                method accepted by the server.  Defaults to
     #                256.
+    # :safe_level :: The safe level of the DRbServer.  The attribute
+    #                sets $SAFE for methods performed in the main_loop.
+    #                Defaults to 0.
     #
     # The default values of these options can be modified on
     # a class-wide basis by the class methods #default_argc_limit,
@@ -1385,7 +1403,10 @@ module DRb
     # The configuration of this DRbServer
     attr_reader :config
 
-    # The safe level for this server
+    # The safe level for this server.  This is a number corresponding to
+    # $SAFE.
+    #
+    # The default safe_level is 0
     attr_reader :safe_level
 
     # Set whether to operate in verbose mode.
@@ -1741,7 +1762,10 @@ module DRb
   end
   module_function :thread
 
-  # Set the default id conv object.
+  # Set the default id conversion object.
+  #
+  # This is expected to be an instance such as DRb::DRbIdConv that responds to
+  # #to_id and #to_obj that can convert objects to and from DRb references.
   #
   # See DRbServer#default_id_conv.
   def install_id_conv(idconv)
@@ -1749,7 +1773,7 @@ module DRb
   end
   module_function :install_id_conv
 
-  # Set the default acl.
+  # Set the default ACL to +acl+.
   #
   # See DRb::DRbServer.default_acl.
   def install_acl(acl)
@@ -1766,7 +1790,16 @@ module DRb
   @server = {}
   # Registers +server+ with DRb.
   #
+  # This is called when a new DRb::DRbServer is created.
+  #
   # If there is no primary server then +server+ becomes the primary server.
+  #
+  # Example:
+  #
+  #  require 'drb'
+  #
+  #  s = DRb::DRbServer.new # automatically calls regist_server
+  #  DRb.fetch_server s.uri #=> #<DRb::DRbServer:0x...>
   def regist_server(server)
     @server[server.uri] = server
     mutex.synchronize do
@@ -1775,13 +1808,15 @@ module DRb
   end
   module_function :regist_server
 
-  # Removes +server+ from the list of servers.
+  # Removes +server+ from the list of registered servers.
   def remove_server(server)
     @server.delete(server.uri)
   end
   module_function :remove_server
 
   # Retrieves the server with the given +uri+.
+  #
+  # See also regist_server and remove_server.
   def fetch_server(uri)
     @server[uri]
   end