From b58b29794855c7d70a3488c5bf122172ce2cfb85 Mon Sep 17 00:00:00 2001
From: Jamis Buck <jamis@37signals.com>
Date: Wed, 9 Apr 2008 17:15:41 -0600
Subject: document DynamicServer and ServerList

---
 lib/net/ssh/multi/dynamic_server.rb | 34 +++++++++++++++++++++++++++++++---
 lib/net/ssh/multi/server_list.rb    | 25 ++++++++++++++++++++++---
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/lib/net/ssh/multi/dynamic_server.rb b/lib/net/ssh/multi/dynamic_server.rb
index 92af7a5..336dca7 100644
--- a/lib/net/ssh/multi/dynamic_server.rb
+++ b/lib/net/ssh/multi/dynamic_server.rb
@@ -2,24 +2,54 @@ require 'net/ssh/multi/server'
 
 module Net; module SSH; module Multi
 
+  # Represents a lazily evaluated collection of servers. This will usually be
+  # created via Net::SSH::Multi::Session#use(&block), and is useful for creating
+  # server definitions where the name or address of the servers are not known
+  # until run-time.
+  #
+  #   session.use { lookup_ip_address_of_server }
+  #
+  # This prevents +lookup_ip_address_of_server+ from being invoked unless the
+  # server is actually needed, at which point it is invoked and the result
+  # cached.
+  #
+  # The callback should return either +nil+ (in which case no new servers are
+  # instantiated), a String (representing a connection specification), an
+  # array of Strings, or an array of Net::SSH::Multi::Server instances.
   class DynamicServer
+    # The Net::SSH::Multi::Session instance that owns this dynamic server record.
     attr_reader :master
+
+    # The Proc object to call to evaluate the server(s)
     attr_reader :callback
+
+    # The hash of options that will be used to initialize the server records.
     attr_reader :options
 
+    # Create a new DynamicServer record, owned by the given Net::SSH::Multi::Session
+    # +master+, with the given hash of +options+, and using the given Proc +callback+
+    # to lazily evaluate the actual server instances.
     def initialize(master, options, callback)
       @master, @options, @callback = master, options, callback
       @servers = nil
     end
 
+    # Returns the value for the given +key+ in the :properties hash of the
+    # +options+. If no :properties hash exists in +options+, this returns +nil+.
     def [](key)
       (options[:properties] || {})[key]
     end
 
+    # Iterates over every instantiated server record in this dynamic server.
+    # If the servers have not yet been instantiated, this does nothing (e.g.,
+    # it does _not_ automatically invoke #evaluate!).
     def each
       (@servers || []).each { |server| yield server }
     end
 
+    # Evaluates the callback and instantiates the servers, memoizing the result.
+    # Subsequent calls to #evaluate! will simply return the cached list of
+    # servers.
     def evaluate!
       @servers ||= Array(callback[options]).map do |server|
           case server
@@ -29,9 +59,7 @@ module Net; module SSH; module Multi
         end
     end
 
-    def to_ary
-      evaluate!
-    end
+    alias to_ary evaluate!
   end
 
 end; end; end
\ No newline at end of file
diff --git a/lib/net/ssh/multi/server_list.rb b/lib/net/ssh/multi/server_list.rb
index 1f83be3..da1914f 100644
--- a/lib/net/ssh/multi/server_list.rb
+++ b/lib/net/ssh/multi/server_list.rb
@@ -3,13 +3,23 @@ require 'net/ssh/multi/dynamic_server'
 
 module Net; module SSH; module Multi
 
+  # Encapsulates a list of server objects, both dynamic (Net::SSH::Multi::DynamicServer)
+  # and static (Net::SSH::Multi::Server). It attempts to make it transparent whether
+  # a dynamic server set has been evaluated or not. Note that a ServerList is
+  # NOT an Array, though it is Enumerable.
   class ServerList
     include Enumerable
 
+    # Create a new ServerList that wraps the given server list. Duplicate entries
+    # will be discarded.
     def initialize(list=[])
       @list = list.uniq
     end
 
+    # Adds the given server to the list, and returns the argument. If an
+    # identical server definition already exists in the collection, the
+    # argument is _not_ added, and the existing server record is returned
+    # instead.
     def add(server)
       index = @list.index(server)
       if index
@@ -20,11 +30,17 @@ module Net; module SSH; module Multi
       server
     end
 
+    # Adds an array (or otherwise Enumerable list) of servers to this list, by
+    # calling #add for each argument. Returns +self+.
     def concat(servers)
       servers.each { |server| add(server) }
       self
     end
 
+    # Iterates over each distinct server record in the collection. This will
+    # correctly iterate over server records instantiated by a DynamicServer
+    # as well, but only if the dynamic server has been "evaluated" (see
+    # Net::SSH::Multi::DynamicServer#evaluate!).
     def each
       @list.each do |server|
         case server
@@ -36,11 +52,16 @@ module Net; module SSH; module Multi
       self
     end
 
+    # Works exactly as Enumerable#select, but returns the result as a new
+    # ServerList instance.
     def select
       subset = @list.select { |i| yield i }
       ServerList.new(subset)
     end
 
+    # Returns an array of all servers in the list, with dynamic server records
+    # expanded. The result is an array of distinct server records (duplicates
+    # are removed from the result).
     def flatten
       result = @list.inject([]) do |aggregator, server|
         case server
@@ -53,9 +74,7 @@ module Net; module SSH; module Multi
       result.uniq
     end
 
-    def to_ary
-      flatten
-    end
+    alias to_ary flatten
   end
 
 end; end; end
\ No newline at end of file
-- 
cgit v1.2.1