1 files changed, 22 insertions, 3 deletions

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