rubylabs 0.9.0 → 0.9.1

data/lib/tsplab.rb

@@ -1,23 +1,18 @@
+module RubyLabs
+  
 =begin rdoc
 
-== Traveling Salesman Lab
+== TSPLab
 
-=end
+The TSPLab module has definitions of classes and methods used in the projects for Chapter 12
+of <em>Explorations in Computing</em>.  The experiments in this chapter are on the Traveling
+Salesman Problem and techniques for solving it with a genetic algorithm.  A class called Map
+implements a symmetric matrix to represent driving distances, and a class called Tour
+represents paths that connect every point on a map.  In the genetic algorithm, a "population"
+is simply an array of Tour objects, and methods gradually evolve a solution by throwing out
+high cost tours and replacing them with new tours that are slight variations of the survivors.
 
-=begin
-  todo unit tests
-  todo keep track of how tour made, color those from crosses a different color
-  todo ? later -- hightlight changes when drawing tour
-  todo possible error in call to m.make_tour(:mutate,t) when t is not full size tour of m
-  todo kinda brittle with popsize param -- interaction between histogram and popsize needs 
-          to be stabilized (see esp need to pass popsize to rebuild_population)
-  todo fix labels -- top level methods need to erase labels from rsearch or other experiments
-  todo to_s for maps should print : in front of symbol labels
-  todo clean up rsearch, add :begin/:end wrapper
-  todo catch ^C interrupt in esearch?  each_permutation?
 =end
-
-module RubyLabs
   
 module TSPLab
 
@@ -27,181 +22,270 @@ module TSPLab
   MapView = Struct.new(:cities, :nodes, :links, :labels, :histogram, :options)
   ItemWithDirection = Struct.new(:value, :direction)
   
+  # An ItemWithDirection is a struct with two fields, a numeric value and a character that
+  # represents right or left, used by the Johnson-Trotter algorithm that generates permutations
+  # of points on a map.
+  
   class ItemWithDirection
-    def inspect
+    def inspect   # :nodoc:
       (self.direction ? "<" : ">") + self.value.inspect
     end
   end
   
 =begin rdoc
-  A Map is a 2D array of distances between pairs of cities.  A new Map object
-  will initially be empty.  Call m[i,j] = x to assign the distance between i and
-  j.  Maps are symmetric (i.e. m[i,j] == m[j,i] for all i and j) so assigning a
-  value to m[i,j] automatically assigns the same value to m[j,i].  Indices can be 
-  strings, symbols, or integers.
+
+== Map
+
+A Map is a 2D array of distances between pairs of cities.  Use the index operator to 
+look up the distance between two points.  For example, given a Map object +m+, 
+call <tt>m[i,j] to find the distance between cities +i+ and
++j+.  Indices +i+ and +j+ can be symbols or integers.
+
 =end
   
   class Map
 
-  	# Make a new distance matrix.
+    # Create a new Map object.  If the argument is an integer +n+, make a map with +n+
+    # cities at random locations (see the method make_random_map for a description of
+    # how the cities are chosen).  If the argument is a symbol, read a file with that
+    # name from the TSPLab data directory.  If the argument is a string, look for a file
+    # with that name in the current directory.
+    #
+    # Example:
+    #    >> m = Map.new(10)
+    #    => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9]>
+    #    >> m = Map.new(:ireland)
+    #    => #<TSPLab::Map [belfast,cork,dublin,galway,limerick]>
 
     def initialize(arg)
-  		@labels = Array.new
-  		@dist = Array.new
-  		@coords = Array.new
+      @labels = Array.new
+      @dist = Array.new
+      @coords = Array.new
       if arg.class == String || arg.class == Symbol
         read_file(arg)
       elsif arg.class == Fixnum
         make_random_map(arg)
-      elsif arg.class == Array
-        make_map(arg)
-      elsif arc.class != NilClass
-        raise "Map.new: parameter must be a file name, array of points, or an integer"
+      # elsif arg.class == Array
+      #   make_map(arg)
+      else
+        raise "Map.new: parameter must be a symbol, a file name, or an integer"
       end
     end
 
+    # Generate a string that lists the cities in this map object.
+    
     def inspect
       sprintf "#<TSPLab::Map [%s]>", @labels.join(",") 
     end
   
     alias to_s inspect
 
-  	# print the current state of the metric; the parameter is the field width (number
-  	# of chars in each matrix entry)
-
-  	def display(fw = nil)
-  	  if fw.nil?
+    # Print the complete set of driving distances in the map in the form of a 
+    # symmetric matrix.  The argument is the field width (number
+    # of chars in each matrix entry).  If no argument is passed, the method uses the
+    # number of letters in the longest city name as the field width.
+    #
+    # Example:
+    #    >> m = Map.new(:ireland)
+    #    => #<TSPLab::Map [belfast,cork,dublin,galway,limerick]>
+    #    >> m.display
+    #              belfast     cork   dublin   galway limerick 
+    #     belfast      0.00
+    #        cork    425.00     0.00
+    #      dublin    167.00   257.00     0.00
+    #      galway    306.00   209.00   219.00     0.00
+    #    limerick    323.00   105.00   198.00   105.00     0.00
+
+    def display(fw = nil)
+      if fw.nil?
         lw = labels.inject(0) { |max, x| n = x.to_s.length;  (n > max) ? n : max }
         dw = (log10(@maxdist).ceil+4)
         fw = max(lw+1,dw)
-	    end
+      end
       res = " " * fw
       @labels.each { |name| res << sprintf("%#{fw-1}s ", name.to_s[0..fw-1]) }
       res += "\n"
-  		@dist.each_with_index do |a,i| 
-  		  res += sprintf("%#{fw-1}s ", @labels[i].to_s[0..fw-1])
-  			a.each { |x| res += (x.nil? ? "  --  " : sprintf("%#{fw}.2f", x)) }
-  			res += "\n"
-  		end
-  		puts res
-  	end
-  	
-  	# method to make tours
-  	
-  	def make_tour(*args)
-  	  begin
-  	    args << :any if args.length == 0
-  	    case args[0]
-	      when :any
-	        tour = Tour.new(self, labels)    # note labels returns clone of @labels array...
-  	    when :random
-  	      tour = Tour.new(self, permute!(labels))
-	      when :mutate
-	        raise "usage" unless args.length >= 2 && args[1].class == Tour && (args[2].nil? || args[2].class == Fixnum)
-  	      child = args[1].clone
-  	      dmax = args[2] ? args[2] : 1
-  	      i = rand(size)
+      @dist.each_with_index do |a,i| 
+        res += sprintf("%#{fw-1}s ", @labels[i].to_s[0..fw-1])
+        a.each { |x| res += (x.nil? ? "  --  " : sprintf("%#{fw}.2f", x)) }
+        res += "\n"
+      end
+      puts res
+    end
+    
+    # Creat a new Tour object that represents a path that connects cities
+    # in this map.  If the argument is an array of city names, the tour will include 
+    # just these cities, in the order they are given (the array does not have to include
+    # all the cities).  If the method is called without any arguments it returns a tour
+    # that contains all the cities in the order in which they were defined.  The third
+    # situation is to pass a symbol as the first argument in the call, in which case the
+    # symbol specifies how the new tour is created:
+    # <tt>  m.make_tour(:random)</tt>:: make a complete tour of all cities in a random order
+    # <tt>  m.make_tour(:mutate, t1)</tt>:: the new tour is a copy of <tt>t1</tt> with a single point mutation
+    # <tt>  m.make_tour(:cross, t1, t2)</tt>:: the new tour is a cross between tours <tt>t1</tt> and <tt>t2</tt>.
+    #
+    # Example:
+    #    >> m = Map.new(10)
+    #    => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9]>
+    #    >> m.make_tour([2,4,6])
+    #    => #<TSPLab::Tour [2, 4, 6] (871.38)>
+    #    >> t1 = m.make_tour
+    #    => #<TSPLab::Tour [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] (2161.70)>
+    #    >> t2 = m.make_tour(:random)
+    #    => #<TSPLab::Tour [8, 6, 7, 5, 4, 0, 1, 9, 2, 3] (2294.16)>
+    #    >> m.make_tour(:mutate, t1)
+    #    => #<TSPLab::Tour [0, 1, 2, 3, 5, 4, 6, 7, 8, 9] (2426.67)>
+    #    >> m.make_tour(:cross, t1, t2)
+    #    => #<TSPLab::Tour [4, 5, 6, 7, 8, 9, 0, 1, 2, 3] (2161.70)>    
+
+    def make_tour(*args)
+      begin
+        args << :nil if args.length == 0
+        case args[0]
+        when :nil
+          tour = Tour.new(self, labels)    # note labels returns clone of @labels array...
+        when :random
+          tour = Tour.new(self, permute!(labels))
+        when :mutate
+          raise "usage" unless args.length >= 2 && args[1].class == Tour && (args[2].nil? || args[2].class == Fixnum)
+          child = args[1].clone
+          dmax = args[2] ? args[2] : 1
+          i = rand(size)
           d = 1 + rand(dmax)
           # puts "mutate #{i} #{d}"
-      	  tour = child.mutate!(i,d)
-  	      child.parent = args[1]
-  	      child.op = [:mutate, i, d]
-      	when :cross
-	        raise "usage" unless args.length == 3 && args[1].class == Tour && args[2].class == Tour
-  	      child = args[1].clone
-  	      i = rand(size)
-  	      n = 1 + rand(size-1)
+          tour = child.mutate!(i,d)
+          child.parent = args[1]
+          child.op = [:mutate, i, d]
+        when :cross
+          raise "usage" unless args.length == 3 && args[1].class == Tour && args[2].class == Tour
+          child = args[1].clone
+          i = rand(size)
+          n = 1 + rand(size-1)
           # puts "cross #{i} #{n}"
-      	  tour = child.cross!(args[2], i, n)
-      	  child.parent = args[1]
-      	  child.op = [:cross, args[2], i, n]
-      	else
-      	  raise "usage" unless args[0].class == Array
-      	  a = args[0]
-      	  errs = 0
-      	  a.each do |x|
-      	    if ! @labels.include?(x)
-      	      puts "unknown city: #{x}"
-      	      errs += 1
-    	      end
-      	  end
-      	  raise "errors in list of cities" if errs > 0
-      	  tour = Tour.new(self, a)  
-  	    end
-  	  rescue Exception => e
-  	    if e.message == "usage"
-    	    puts "Usage:"
-    	    puts "  make_tour( [x,y,..] )"
-    	    puts "  make_tour( :random )"
-    	    puts "  make_tour( :mutate, t [,n] )"
-    	    puts "  make_tour( :cross, t1, t2 )"
-  	    else
-  	      puts "make_tour: #{e.message}"
-	      end
-  	    return nil
-  	  end
-  	  
+          tour = child.cross!(args[2], i, n)
+          child.parent = args[1]
+          child.op = [:cross, args[2], i, n]
+        else
+          raise "usage" unless args[0].class == Array
+          a = args[0]
+          errs = 0
+          a.each do |x|
+            if ! @labels.include?(x)
+              puts "unknown city: #{x}"
+              errs += 1
+            end
+          end
+          raise "errors in list of cities" if errs > 0
+          tour = Tour.new(self, a)  
+        end
+      rescue Exception => e
+        if e.message == "usage"
+          puts "Usage:"
+          puts "  make_tour( [x,y,..] )"
+          puts "  make_tour( :random )"
+          puts "  make_tour( :mutate, t [,n] )"
+          puts "  make_tour( :cross, t1, t2 )"
+        else
+          puts "make_tour: #{e.message}"
+        end
+        return nil
+      end
+      
       return tour
       
-  	end
-  	  	  	
-  	# Generate all possible tours using the Johnson-Trotter algorithm.  The method
-  	# works by generating all permutations of array indices, then for each permutation
-  	# generating an array of labels.
-  	  	
-  	def each_tour
-  	  a = []
-  	  n = @labels.length
-  	  for i in 1...n do
-  	    a << ItemWithDirection.new(i, true)
-	    end
-  	  loop do
+    end
+            
+    # Generate all possible tours of this map.  Every tour starts in the first
+    # city (city 0 when city names are integers, or the first city read from
+    # the file).  Successive tours are generated by the Johnson-Trotter algorithm,
+    # which generates permutations by exchanging just two cities from the previous
+    # tour.  The Johnson-Trotter algorithm makes it possible to stop iterating
+    # after all unique tours starting from city 0 have been generated.
+    #
+    # Example:
+    #    >> m = Map.new(5)
+    #    => #<TSPLab::Map [0,1,2,3,4]>
+    #    >> m.each_tour { |t| puts t }
+    #    #<TSPLab::Tour [0, 1, 2, 3, 4] (865.11)>
+    #    #<TSPLab::Tour [0, 1, 2, 4, 3] (1042.97)>
+    #    #<TSPLab::Tour [0, 1, 4, 2, 3] (987.40)>
+    #    #<TSPLab::Tour [0, 4, 1, 2, 3] (808.91)>
+    #    #<TSPLab::Tour [0, 4, 1, 3, 2] (741.31)>
+    #    #<TSPLab::Tour [0, 1, 4, 3, 2] (941.69)>
+    #    #<TSPLab::Tour [0, 1, 3, 4, 2] (975.37)>
+    #    #<TSPLab::Tour [0, 1, 3, 2, 4] (843.23)>
+    #    #<TSPLab::Tour [0, 3, 1, 2, 4] (842.59)>
+    #    #<TSPLab::Tour [0, 3, 1, 4, 2] (919.17)>
+    #    #<TSPLab::Tour [0, 3, 4, 1, 2] (941.06)>
+    #    #<TSPLab::Tour [0, 4, 3, 1, 2] (796.88)>
+    #    => nil
+        
+    def each_tour
+      a = []
+      n = @labels.length
+      for i in 1...n do
+        a << ItemWithDirection.new(i, true)
+      end
+      loop do
         # yield [0] + a
         yield Tour.new(self, [@labels[0]] + a.map { |x| @labels[x.value] })
-  	    mover = nil
-  	    for i in 0...a.length
-  	      mover = i if movable(a,i) && (mover.nil? || a[i].value > a[mover].value)
+        mover = nil
+        for i in 0...a.length
+          mover = i if movable(a,i) && (mover.nil? || a[i].value > a[mover].value)
         end
-  	    break if mover.nil?
-  	    k = a[mover].value
+        break if mover.nil?
+        k = a[mover].value
         # puts "mover = #{mover} k = #{k}"
-  	    break if k == 2
-  	    adj = a[mover].direction ? mover-1 : mover+1
-  	    a[adj], a[mover] = a[mover], a[adj]
-  	    for i in 0...a.length
-  	      if a[i].value > k
-  	        a[i].direction ^= true 
-	        end
+        break if k == 2
+        adj = a[mover].direction ? mover-1 : mover+1
+        a[adj], a[mover] = a[mover], a[adj]
+        for i in 0...a.length
+          if a[i].value > k
+            a[i].direction ^= true 
+          end
         end
-	    end
-  	end
+      end
+    end
 
-  	# return the number of rows in the matrix
+    # Return the number of cities in this map.
 
-  	def size
-  	  return @dist.length
-  	end
-  	
-  	# return the first pair of city labels
+    def size
+      return @labels.length
+    end
+    
+    # Return the first pair of city labels in this map -- used only by
+    # read_file when loading a map from a file.
 
-  	def first
-  	  return @labels[0..1]
+    def first   # :nodoc:
+      return @labels[0..1]
     end
 
-  	# this iterator will generate the remaining pairs of labels
+    # Iterate over every other pair of city labels except the first -- used
+    # only by read_file when loading a map from a file.
 
-  	def rest
-  		n = @labels.length
-  		@labels.each_with_index do |x,i| 
-  			@labels.last(n-i-1).each_with_index do |y,j|
-  			  next if i == 0 && j == 0
-  				yield(x,y)
-  			end
-  		end
-  	end
+    def rest   # :nodoc:
+      n = @labels.length
+      @labels.each_with_index do |x,i| 
+        @labels.last(n-i-1).each_with_index do |y,j|
+          next if i == 0 && j == 0
+          yield(x,y)
+        end
+      end
+    end
 
-  	# get/set the distance between labels i and j (which can be)
-  	# given in either order, i.e. d[i,j] is the same as d[j,i]
+    # Return the distance between cities +i+ and +j+ (which can be
+    # given in either order, i.e. <tt>d[i,j]</tt> is the same as <tt>d[j,i]</tt>).
+    #
+    # Example:
+    #    >> m = Map.new(:ireland)
+    #    => #<TSPLab::Map [belfast,cork,dublin,galway,limerick]>
+    #    >> m[:cork, :dublin]
+    #    => 257.0
+    #
+    #    >> m = Map.new(10)
+    #    => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9]>
+    #    >> m[6,2]
+    #    => 111.07
 
     def [](i,j)
       ix = @labels.index(i) or return nil
@@ -209,6 +293,12 @@ module TSPLab
       ix, jx = jx, ix if ix < jx
       @dist[ix][jx]
     end
+    
+    # Update the map by assigning a new distance between cities +i+ and +j+.
+    #
+    # Example:
+    #    >> m[6,2] = 110
+    #    => 110
 
     def []=(i,j,val)
       raise "Map: can't assign to diagonal" if i == j
@@ -218,9 +308,25 @@ module TSPLab
       @dist[ix][jx] = val.to_f
     end
 
+    # Return a list of city names for this map.
+    #
+    # Example:
+    #    >> m = Map.new(:ireland)
+    #    => #<TSPLab::Map [belfast,cork,dublin,galway,limerick]>
+    #    >> m.labels
+    #    => [:belfast, :cork, :dublin, :galway, :limerick]
+
     def labels
       return @labels.clone
     end
+    
+    # Return a copy of the distance matrix for this map, in the form of 2D triangular array of Floats.
+    #
+    # Example:
+    #    >> m = Map.new(:ireland)
+    #    => #<TSPLab::Map [belfast,cork,dublin,galway,limerick]>
+    #    >> m.dist
+    #    => [[0.0], [425.0, 0.0], [167.0, 257.0, 0.0], [306.0, 209.0, 219.0, 0.0], [323.0, 105.0, 198.0, 105.0, 0.0]]
 
     def dist
       d = Array.new
@@ -228,18 +334,20 @@ module TSPLab
       return d
     end
     
+    # Return the canvas coordinates of city +x+.
+    
     def coords(x)
       return @coords[index_of(x)]
     end
 
-    # method left over from Metric class, probably not useful for TSP, but...
-
-    def delete(i)
-      ix = @labels.index(i) or return nil
-      (ix...@labels.length).each { |x| @dist[x].slice!(ix) }
-      @dist.slice!(ix)
-      @labels.slice!(ix)
-    end
+    # deprecated
+    # 
+    # def delete(i)
+    #   ix = @labels.index(i) or return nil
+    #   (ix...@labels.length).each { |x| @dist[x].slice!(ix) }
+    #   @dist.slice!(ix)
+    #   @labels.slice!(ix)
+    # end
 
     private
     
@@ -297,17 +405,19 @@ module TSPLab
     def make_random_map(n)
       h = Hash.new
       a = Array.new      
-  		while h.size < n
-  			h[rand(400)] = 1		
-  		end
-  		h.keys.each do |k|
-  		  x = k / 20
-  		  y = k % 20
-  		  a << [x*20 + rand(5) + 50, y*20 + rand(5) + 50]
-  		end    
+      while h.size < n
+        h[rand(400)] = 1    
+      end
+      h.keys.each do |k|
+        x = k / 20
+        y = k % 20
+        a << [x*20 + rand(5) + 50, y*20 + rand(5) + 50]
+      end    
       make_map(a)
     end
-
+    
+    # helper method -- compute and save distances between cities named in array +a+
+    
     def make_map(a)
       @maxdist = 0.0
       for i in 0...a.length
@@ -336,28 +446,42 @@ module TSPLab
   
 
 =begin rdoc
-  A Tour object is an array of city names, corresponding to the cities visited, in order,
-  by the salesman.  Attributes are the path, its cost, a unique tour ID, and a reference to
-  the matrix used to define the distance between pairs of cities.
+
+== Tour
+
+A Tour object is an array of city names, corresponding to the cities visited, in order,
+by the salesman.  Attributes are the path, its cost, a unique tour ID, and a reference to
+the matrix used to define the distance between pairs of cities.
   
-  Class methods access the number of tours created, or reset the tour counter to 0.
+Class methods access the number of tours created, or reset the tour counter to 0.  There
+is a constructor, but users should call the <tt>make_tour</tt> method of the Map class to
+create a new tour instead of calling <tt>Tour.new</tt>.
+#--
+TODO don't give access to path (unless there's a way to make it read-only -- freeze it?)
 =end
 
-  # TODO don't give access to path (unless there's a way to make it read-only -- freeze it?)
-
   class Tour 
     attr_reader :id, :path, :cost, :matrix
     attr_accessor :parent, :op
 
     @@id = 0
     
+    # Set the tour counter back to 0.
+    
     def Tour.reset
       @@id = 0
     end
     
+    # Return the number of Tour objects created.
+    
     def Tour.count
       return @@id
     end
+    
+    # Create a new Tour object for Map +m+, visiting cities in the array +a+.
+    #
+    # NOTE: this method should not be called directly; make a new Tour by calling
+    # Map#make_tour instead.
 
     def initialize(m, s)
       @matrix = m
@@ -366,6 +490,8 @@ module TSPLab
       @id = @@id
       @@id += 1
     end
+    
+    # Create a string that lists the cities in this object, in order, and the tour cost.
 
     def inspect
       sprintf "#<TSPLab::Tour %s (%.2f)>", @path.inspect, @cost
@@ -373,13 +499,29 @@ module TSPLab
 
     alias to_s inspect
 
-    # A copy of a tour needs its own new id and copy of the path and pedigree
+    # Make a "deep copy" of this tour object, giving it a copy of the list of cities.
 
     def clone
       # return Tour.new(@matrix, @path, @nm, @nx)
       return Tour.new(@matrix, @path)
     end
  
+    # Change this tour object by applying a "point mutation" that swaps the city
+    # at location +i+ in the tour with the city +d+ locations away.  +d+ is set to 1 by
+    # default, i.e. if no value is supplied for +d+ the city at location +i+ is
+    # exchanged with the one at location +i++1.
+    #
+    # Example:
+    #    >> t = m.make_tour
+    #    => #<TSPLab::Tour [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] (2281.08)>
+    #    >> t.mutate!(3)
+    #    => #<TSPLab::Tour [0, 1, 2, 4, 3, 5, 6, 7, 8, 9] (1752.78)>
+    #    
+    #    >> t = m.make_tour
+    #    => #<TSPLab::Tour [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] (2281.08)>
+    #    >> t.mutate!(3, 5)
+    #    => #<TSPLab::Tour [0, 1, 2, 8, 4, 5, 6, 7, 3, 9] (1919.38)>  
+    #--
     # Exchange mutation (called 'EM' by Larranaga et al).  Swaps node i with one
     # d links away (d = 1 means neighbor).  An optimization (has a big impact when
     # tours are 20+ cities) computes new cost by subtracting and adding single
@@ -427,6 +569,19 @@ module TSPLab
       self
     end
   
+    # Mutate the current tour by applying a "cross-over" mutation with tour <tt>t2</tt>.
+    # The new path for this object will contain all the cities from locations +i+ through
+    # +j+ in the current path, then all the remaining cities in the order in which they are
+    # found in tour  <tt>t2</tt>.
+    #
+    # Example:
+    #    >> t = m.make_tour
+    #    => #<TSPLab::Tour [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] (2281.08)>
+    #    >> t2 = m.make_tour(:random)
+    #    => #<TSPLab::Tour [8, 1, 3, 2, 7, 6, 4, 0, 9, 5] (2039.49)>
+    #    >> t.cross!(t2, 2, 5)
+    #    => #<TSPLab::Tour [2, 3, 4, 5, 6, 8, 1, 7, 0, 9] (2492.92)>
+    #--
     # Order cross-over (called 'OX1' by Larranaga et al).  Save a chunk of the 
     # current tour, then copy the remaining cities in the order they occur in 
     # tour t.  i is the index of the place to start copying, n is the number to
@@ -448,8 +603,11 @@ module TSPLab
       self
     end
     
-    # Not used normally, but is use in unit tests to make sure mutate! is computing
-    # the right costs with its optimized strategy
+    # Compute the cost of this tour by summing the distances between cities in the 
+    # order shown in the current path.  In general users do not need to call this 
+    # method, since the path is computed when the object is created, and is updated
+    # automatically by calls to <tt>mutate!</tt> and <tt>cross!</tt>, but this method
+    # is used in unit tests to make sure the cost is updated properly by the mutation methods.
         
     def pathcost
       sum = @matrix[ @path[0], @path[-1] ]
@@ -460,9 +618,15 @@ module TSPLab
     end
 
   end # class Tour
-  
-# Combinatorics...  tempting to write factorial with inject, but this is for the 
-# students to look at....
+
+  # Return the value of +n+!, i.e. compute +n+ * +n+-1 * +n+-2 ... 1.
+  #
+  # Example:
+  #   >> factorial(10)
+  #   => 3628800
+  #--
+  # It's tempting to write factorial with inject, but this is for the 
+  # students to look at....
 
   def factorial(n)
     f = 1
@@ -472,11 +636,30 @@ module TSPLab
     return f
   end
   
+  # Compute the number of possible tours for a map with +n+ cities, taking
+  # into account the fact that a tour can start at any of the +n+ cities and
+  # that direction doesn't matter.
+  #
+  # Example:
+  #   >> ntours(10)
+  #   => 181440
+  
   def ntours(n)
     return factorial(n-1) / 2
   end
   
-# Exhaustive search
+  # Do an exhaustive search of all possible tours of cities in map +m+,
+  # returning the tour object that has the lowest cost path.
+  #
+  # Example:
+  #   >> m = Map.new(10)
+  #   => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9]>
+  #   >> ntours(10)
+  #   => 181440
+  #   >> xsearch(m)
+  #   => #<TSPLab::Tour [0, 7, 1, 8, 2, 3, 4, 6, 9, 5] (1027.68)>
+  #   >> time { xsearch(m) }
+  #   => 41.668501  
 
   def xsearch(m)
     best = m.make_tour
@@ -484,15 +667,25 @@ module TSPLab
     return best
   end
   
-# Random search
-  
-
-  def rsearch( matrix, nsamples, userOptions = {} )
+  # Do a random search of the possible tours of cities in map +m+.
+  # Creates +nsamples+ random tour objects and returns the one that
+  # has the lowest cost.  Optional arguments:
+  #   :pause => 0.01     the amount of time (in seconds) to pause between samples
+  #
+  # Example:
+  #   >> m = Map.new(10)
+  #   => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9]>
+  #   >> m.make_tour(:random)
+  #   => #<TSPLab::Tour [1, 4, 5, 6, 7, 2, 8, 9, 3, 0] (2323.46)>
+  #   >> rsearch(m, 100)
+  #   => #<TSPLab::Tour [8, 7, 1, 2, 9, 4, 6, 3, 5, 0] (1356.22)>
+
+  def rsearch( m, nsamples, userOptions = {} )
     options = @@rsearchOptions.merge(userOptions)
     
     Tour.reset
     
-    best = matrix.make_tour(:random)
+    best = m.make_tour(:random)
     if @@drawing
       make_histogram([])      # clear histogram display
       view_tour(best) 
@@ -500,7 +693,7 @@ module TSPLab
     end
     
     (nsamples-1).times do |i|
-      t = matrix.make_tour(:random)
+      t = m.make_tour(:random)
       if t.cost < best.cost
         best = t
         if @@drawing
@@ -517,11 +710,19 @@ module TSPLab
     return best
   end
 
-=begin rdoc
-  Make a set of +n+ random tours from map +m+
-=end
-
-# :begin :init_population
+  # Create an array with +n+ random tours of the cities in map +m+.  The tours
+  # will be sorted in order of increasing path cost.  If the canvas is open,
+  # a histogram of tour costs is displayed.
+  #
+  # Example:
+  #    >> p = init_population(m, 10)
+  #    => [ #<TSPLab::Tour [1, 4, 3, 5, 0, 8, 6, 9, 2, 7] (1823.65)>,
+  #         #<TSPLab::Tour [5, 1, 7, 8, 9, 4, 3, 2, 0, 6] (1835.27)>,
+  #         ...
+  #         #<TSPLab::Tour [1, 5, 6, 3, 8, 4, 2, 0, 7, 9] (2446.24)>,
+  #         #<TSPLab::Tour [3, 2, 9, 8, 5, 4, 1, 0, 6, 7] (2765.43)> ]
+  #--
+  # :begin :init_population
   def init_population( m, n )
     a = Array.new
 
@@ -537,48 +738,90 @@ module TSPLab
     
     return a
   end
-# :end :init_population
-  
-  
-=begin rdoc
-  +select_survivors(p, options)+  Apply "natural selection" to population +p+.  Sort by 
-  fitness, then remove individual +i+ with probability +i/n+ where +n+ is the population
-  size.  Note the first item in the array is always kept since +0/n = 0+.
-=end
-
-# p.sort! { |x,y| (x.cost == y.cost) ? (x.id <=> y.id) : (x.cost <=> y.cost) }
-
-# :begin :select_survivors
+  # :end :init_population
+   
+  # Apply "natural selection" to +population+, which should be an array of tour objects.  Sort 
+  # the array by 
+  # fitness, then remove individual +i+ with probability +i+/+n+ where +n+ is the population
+  # size.  Note the first item in the array is always kept since 0/+n+ = 0.
+  #
+  # Example:
+  #   >> p = init_population(m, 10)
+  #   => [#<TSPLab::Tour [6, 14, 8, 11, 9, 7, 12, 0, 5, 4, 3, 2, 10, 13, 1] (2926.67)>, 
+  #       #<TSPLab::Tour [13, 6, 3, 2, 12, 7, 4, 10, 5, 1, 8, 11, 9, 14, 0] (3069.48)>, 
+  #       ...
+  #       #<TSPLab::Tour [5, 9, 1, 14, 10, 8, 0, 4, 2, 13, 3, 6, 7, 11, 12] (3455.32)>, 
+  #       #<TSPLab::Tour [0, 4, 6, 14, 2, 5, 7, 8, 11, 9, 10, 12, 13, 3, 1] (3511.14)>]
+  #   >> p.length
+  #   => 10
+  #   >> select_survivors(p)
+  #   => [#<TSPLab::Tour [6, 14, 8, 11, 9, 7, 12, 0, 5, 4, 3, 2, 10, 13, 1] (2926.67)>, 
+  #       #<TSPLab::Tour [10, 14, 6, 12, 9, 7, 11, 13, 3, 2, 4, 8, 0, 5, 1] (3119.66)>, 
+  #       #<TSPLab::Tour [6, 10, 7, 12, 13, 4, 1, 2, 11, 14, 0, 3, 9, 8, 5] (3156.77)>, 
+  #       #<TSPLab::Tour [11, 10, 1, 0, 5, 12, 8, 13, 2, 14, 6, 4, 7, 9, 3] (3206.06)>]
+  #   >> p.length
+  #   => 4
+  #--
+  # This version of the call to sort! keeps the first tour created if there is a tie:
+  #    p.sort! { |x,y| (x.cost == y.cost) ? (x.id <=> y.id) : (x.cost <=> y.cost) }
+  #
+  # This version of the method uses two phases when the map is shown on the screen, in
+  # order to display deleted populations as gray bars in the histogram.
+  # :begin :select_survivors
   def select_survivors( population, toplevel = true )
     population.sort! { |x,y| x.cost <=> y.cost }
     n = population.size
     
     (n-1).downto(1) do |i|
       if ( rand < (i.to_f / n) )
-        # population.delete_at(i) 
-        population[i].op = :zap 
+        if @@drawing && toplevel
+          population[i].op = :zap 
+        else
+          population.delete_at(i)
+        end
       end
     end
     
     if @@drawing && toplevel
-      show_survivors( population ) 
+      show_survivors( population )     
+      (n-1).downto(1) do |i|
+        population.delete_at(i) if population[i].op == :zap
+      end
     end
     
     return population
   end
-# :end :select_survivors
-
-=begin rdoc
-  +rebuild_population(p, n, options)+  Add new Tour objects to population +p+ until the size
-  of the population reaches +n+.  Each new Tour is a mutation of one or two Tours currently
-  in +p+.  The hash +options+ has mutation parameters, e.g. the probability of doing a crossover
-  vs. point mutation.
-=end
-
-# :begin :rebuild_population
+  # :end :select_survivors
+
+  # Add new tours to +population+, which should be an array of Tour objects, until the size
+  # of the array reaches +n+.  Each new tour is a mutation of one or two tours currently
+  # in +p+.  The optional arguments is an expression of the form <tt>:distribution => :x</tt> where +x+
+  # is an array of three floating point numbers corresponding to the probability of a small point mutation, 
+  # the probability of a large point mutation, and the probability of a crossover.  The three numbers
+  # must sum to 1.0.  For convenience, instead of passing an array, the argument +x+ can be the name
+  # of one of the predefined distributions:
+  #     :mixed        [0.5, 0.25, 0.25]
+  #     :all_small    [1.0, 0.0, 0.0]
+  #     :all_large    [0.0, 1.0, 0.0]
+  #     :all_cross    [0.0, 0.0, 1.0]
+  # The distribution name can also be <tt>:random</tt>, in which case new tours are not mutations of
+  # existing tours but rather random tours.
+  # If no distribution is specified the default is <tt>:all_small</tt>
+  #
+  # Example:
+  #   >> rebuild_population(pop, 10)
+  #   => [#<TSPLab::Tour [2, 7, 4, 11, 12, 6, 5, 14, 3, 0, 13, 9, 10, 1, 8] (2224.71)>, 
+  #       ...
+  #       #<TSPLab::Tour [2, 7, 4, 11, 12, 6, 5, 14, 3, 0, 13, 9, 8, 10, 1] (2485.64)>]
+  # 
+  #   >> rebuild_population(pop, 20, :distribution => :mixed)
+  #   => [#<TSPLab::Tour [2, 7, 4, 11, 12, 6, 5, 14, 3, 0, 13, 9, 10, 1, 8] (2224.71)>,
+  #       ...
+  #       #<TSPLab::Tour [14, 3, 0, 13, 9, 10, 1, 2, 7, 4, 11, 12, 6, 5, 8] (2329.32)>]
+  #--
+  # :begin :rebuild_population
   def rebuild_population( population, popsize, userOptions = {} )
     options = @@esearchOptions.merge(userOptions)
-    tracing = (options[:trace] == :on)
     
     map = population[0].matrix      # assume they're all from the same map...
     
@@ -586,10 +829,6 @@ module TSPLab
     psmall, plarge, pcross = options[:profiles][dist]
     sdmax  = options[:sdmax] || ((map.size > 10) ? (map.size / 10) : 1)
     ldmax  = options[:ldmax] || ((map.size > 10) ? (map.size / 4) : 1)
-
-    (popsize-1).downto(1) do |i|
-      population.delete_at(i) if population[i].op == :zap
-    end
     
     prev = population.length        # items before this index are from previous generation
 
@@ -599,14 +838,14 @@ module TSPLab
         kid = map.make_tour( :random )
       elsif r < 1.0 - (plarge + pcross)
         mom = population[ rand(prev) ]
-  	    kid = map.make_tour( :mutate, mom, sdmax )
-	    elsif r < 1.0 - pcross
+        kid = map.make_tour( :mutate, mom, sdmax )
+      elsif r < 1.0 - pcross
         mom = population[ rand(prev) ]
-  	    kid = map.make_tour( :mutate, mom, ldmax )
+        kid = map.make_tour( :mutate, mom, ldmax )
       else
         mom = population[ rand(prev) ]
         dad = population[ rand(prev) ]
-  	    kid = map.make_tour( :cross, mom, dad )
+        kid = map.make_tour( :cross, mom, dad )
       end
       population << kid
     end
@@ -617,9 +856,26 @@ module TSPLab
 
     return population
   end
-# :end :rebuild_population
-
-# :begin :evolve
+  # :end :rebuild_population
+  
+  # Main loop of the genetic algorithm to find the optimal tour of a set of cities.
+  # +population+ is an array of tour objects (see init_population).  +maxgen+ is the
+  # number of rounds of selection and rebuilding to execute.  The third argument is
+  # usually omitted, but might be set when this method is called from esearch.  It is
+  # used to continue a previous search.  For example, if an earlier search ran for 100
+  # generations, to continue for another 100 generations, esearch will call this method
+  # with +maxgen+ = 200 and +ngen+ = 100.  Any options passed after +ngen+ will be passed
+  # on to rebuild_population, to specify which mutation parameters to use.
+  #
+  # Example -- create a population and evolve it over 100 generations:
+  #   >> p = init_population(m, 10)
+  #   => [#<TSPLab::Tour [0, 5, 9, 13, 12, 10, 11, 4, 8, 14, 2, 7, 1, 6, 3] (2853.56)>, 
+  #       ...
+  #       #<TSPLab::Tour [9, 14, 13, 3, 11, 6, 5, 0, 8, 10, 1, 4, 7, 2, 12] (3527.98)>]
+  #   >> evolve(p, 100)
+  #   => #<TSPLab::Tour [5, 0, 13, 12, 9, 10, 11, 8, 4, 14, 7, 1, 2, 6, 3] (2376.64)>
+  #--
+  # :begin :evolve
   def evolve( population, maxgen, ngen = 0, options = {} )
     popsize = population.length
     best = population[0]
@@ -629,7 +885,6 @@ module TSPLab
       if (population[0].cost - best.cost).abs > 1e-10
         best = population[0] 
         updated = true
-        # @@bestGeneration = ngen
       else
         updated = false
       end
@@ -638,18 +893,33 @@ module TSPLab
     end    
     return best
   end
-# :end :evolve
-
-=begin rdoc
-  +esearch( map, n, options)+  Top level method for the genetic algorithm.  +m+ is a Map
-  containing pairwise distances between a set of cities.  The hash named
-  +options+ contains tour parameters, e.g. population size and mutation probabilities.
-  Make an initial population of random tours, then iterate +n+ times, calling +select_survivors+
-  and +rebuild_population+ to evolve an optimal tour.  The return value is the lowest cost
-  tour after the last round of evolution.
-=end
-
-  def esearch( matrix, maxgen, userOptions = {} )
+  # :end :evolve
+
+  # Use an evolutionary algorithm to search for the optimal tour of the cities on a map +m+.
+  # The +maxgen+ argument is the number of cycles of selection and rebuilding to perform.
+  # The return value is the tour object with the lowest cost in the final population.
+  #
+  # The optional arguments following +maxgen+ specify parameters of the evolutionary algorithm.  Possible options
+  # and their defaults are:
+  #    :popsize => 10                  population size
+  #    :distribution => :all_small     (see note below)
+  #    :pause => 0.02                  time (in seconds) to pause between each generation
+  # The distribution option can be an array of Floats or one of the symbols <tt>:mixed</tt>, <tt>:random</tt>, 
+  # <tt>:all_small</tt>, 
+  # <tt>:all_large</tt>, or <tt>:all_cross</tt> passed to the rebuild_population method (see the
+  # documentation of that method for an explanation).
+  #
+  # Example:
+  #   >> m = Map.new(15)
+  #   => #<TSPLab::Map [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14]>
+  #   >> esearch(m, 100)
+  #   => #<TSPLab::Tour [7, 14, 6, 9, 3, 10, 2, 1, 5, 0, 13, 8, 12, 4, 11] (1823.57)>
+  #   >> esearch(m, 100, :distribution => :mixed)
+  #   => #<TSPLab::Tour [6, 9, 3, 12, 8, 4, 2, 10, 11, 13, 0, 5, 1, 7, 14] (1472.27)>
+  #   >> esearch(m, 100, :distribution => [0.5, 0.0, 0.5])
+  #   => #<TSPLab::Tour [3, 4, 1, 6, 7, 9, 14, 11, 5, 8, 2, 13, 10, 12, 0] (1581.29)>  
+
+  def esearch( m, maxgen, userOptions = {} )
     options = @@esearchOptions.merge(userOptions)
     
     if options[:continue]
@@ -663,7 +933,7 @@ module TSPLab
       end
     else
       Tour.reset
-      population = init_population( matrix, options[:popsize] )
+      population = init_population( m, options[:popsize] )
       ngen = 0
       if @@drawing
         init_labels(["generations:", "tours:", "cost:"])
@@ -687,60 +957,45 @@ module TSPLab
     return population[0]
   end
   
-  def update_tour_display(population, ngen, new_tour, dt)
-    if new_tour
-      view_tour(population[0]) 
-      @@drawing.labels[2].update(sprintf( "cost: %.2f", population[0].cost ))
-    end
-    update_histogram(population)
-    @@drawing.labels[0].update(sprintf( "generations: %d", ngen ))
-    @@drawing.labels[1].update(sprintf( "#tours: %d", Tour.count ))
-    sleep dt
-  end
-  
-=begin rdoc
-  Make sure the mutation parameters are valid
-=end
-
-  def check_mutation_parameters(options)
-    dist = options[:distribution]
-    profiles = options[:profiles]
-    raise "specify mutation probabilities with :distribution option" unless dist
-    floaterr = "distribution must be an array of three numbers between 0.0 and 1.0"
-    symbolerr = "distribution must be one of #{profiles.keys.inspect}"
-    if dist.class == Symbol
-      raise symbolerr unless profiles[dist]
-    elsif dist.class == Array
-      raise floaterr unless dist.length == 3
-      sum = 0.0
-      dist.each { |x| raise floaterr if (x < 0.0 || x > 1.0); sum += x}
-      raise "sum of probabilities must be 1.0" unless (sum - 1).abs < Float::EPSILON
-      profiles[:user] = dist
-      options[:distribution] = :user
-    else
-      raise "#{floaterr} or #{symbolerr}"
-    end
-  end
-  
-  def checkout(matrix, filename = nil)
-    matrixfilename = matrix.to_s + ".txt"
+  # Save a copy of a map from the TSPLab data directory in the current working directory.
+  # If the +filename+ argument is not specified the new file will be the name of the map
+  # with ".txt" appended.
+  #
+  # Example:
+  #   >> checkout(:ireland, "my_ireland_map.txt")
+  #   Copy of ireland saved in my_ireland_map.txt
+  #   => nil
+    
+  def checkout(m, filename = nil)
+    matrixfilename = m.to_s + ".txt"
     matrixfilename = File.join(@@tspDirectory, matrixfilename)
     if !File.exists?(matrixfilename)
-      puts "Matrix not found: #{matrixfilename}"
+      puts "Map not found: #{matrixfilename}"
       return nil
     end
-    outfilename = filename.nil? ? (matrix.to_s + ".txt") : filename
+    outfilename = filename.nil? ? (m.to_s + ".txt") : filename
     dest = File.open(outfilename, "w")
-	  File.open(matrixfilename).each do |line|
-	    dest.puts line.chomp
-	  end
+    File.open(matrixfilename).each do |line|
+      dest.puts line.chomp
+    end
     dest.close
-    puts "Copy of #{matrix} saved in #{outfilename}"
+    puts "Copy of #{m} saved in #{outfilename}"
   end
   
-=begin rdoc
-  Methods for displaying a map and a tour
-=end
+  # Initialize the RubyLabs Canvas and draw the cities in map +m+.  The locations
+  # of the cities are defined when the map is created.  For maps distributed in
+  # the TSPLab data area (e.g. <tt>:ireland</tt>) the +x+ and +y+ coordinates of
+  # each city are part of the data file.  For random maps, cities are placed randomly
+  # on the map.
+  #
+  # Options for controlling the color and size of a circle representing a city can
+  # be passed following +m+.  The options, and their defaults, are:
+  #   :dotColor => '#cccccc'
+  #   :dotRadius => 5.0
+  #
+  # Example -- display the cities in map +m+ with large green circles:
+  #   >> view_map(m, :dotRadius => 10, :dotColor => 'darkgreen')
+  #   => true
 
   def view_map(m, userOptions = {} )
     options = @@mapOptions.merge(userOptions)
@@ -757,6 +1012,11 @@ module TSPLab
     return true    
   end
   
+  # Update the drawing on the RubyLabs canvas to show the paths in tour object +t+.
+  # Raises an error if the user has not yet called view_map to draw the locations of
+  # the cities first.  A call to view_tour will erase an existing tour and then draw
+  # a new set of lines showing the path defined by +t+.
+  
   def view_tour(t, userOptions = {} )
     if @@drawing.nil?
       puts "call view_map to initialize the canvas"
@@ -776,11 +1036,58 @@ module TSPLab
     @@drawing.nodes.each { |x| x.raise }
     return true
   end
+        
+  private
   
-=begin rdoc
-  Initialize a set of text label objects.  Erase any old labels saved
-  for this drawing, replace them with new ones.
-=end
+  # Helper method, called from evolve to update the best tour and the displayed text
+  
+  def update_tour_display(population, ngen, new_tour, dt)
+    if new_tour
+      view_tour(population[0]) 
+      @@drawing.labels[2].update(sprintf( "cost: %.2f", population[0].cost ))
+    end
+    update_histogram(population)
+    @@drawing.labels[0].update(sprintf( "generations: %d", ngen ))
+    @@drawing.labels[1].update(sprintf( "#tours: %d", Tour.count ))
+    sleep dt
+  end
+  
+  # Helper method, called from select_survivors to update the histogram to show which
+  # tours have been deleted.
+  
+  def show_survivors(pop)
+    hist = @@drawing.histogram
+    return unless pop.length == hist.length
+    hist.each_with_index do |box, i|
+      box.fill = 'gray' if pop[i].op == :zap
+    end
+    @@recolor = true
+  end
+  
+  # Helper method, called from esearch to validate items passed in the options hash
+
+  def check_mutation_parameters(options)
+    dist = options[:distribution]
+    profiles = options[:profiles]
+    raise "specify mutation probabilities with :distribution option" unless dist
+    floaterr = "distribution must be an array of three numbers between 0.0 and 1.0"
+    symbolerr = "distribution must be one of #{profiles.keys.inspect}"
+    if dist.class == Symbol
+      raise symbolerr unless profiles[dist]
+    elsif dist.class == Array
+      raise floaterr unless dist.length == 3
+      sum = 0.0
+      dist.each { |x| raise floaterr if (x < 0.0 || x > 1.0); sum += x}
+      raise "sum of probabilities must be 1.0" unless (sum - 1).abs < Float::EPSILON
+      profiles[:user] = dist
+      options[:distribution] = :user
+    else
+      raise "#{floaterr} or #{symbolerr}"
+    end
+  end
+  
+  # Helper method called by rsearch and esearch to create text strings on the display
+  # (for showing the cost of the best tour, etc.)
   
   def init_labels(a)
     labelx = 525
@@ -796,17 +1103,10 @@ module TSPLab
     end
     return @@drawing.labels
   end
-  
-  # def update_labels(a)
-  #   labels = @@drawing.labels
-  #   for i in 0...labels.length
-  #     labels[i].update(a[i])
-  #   end
-  # end
-  
-  # todo! color bin red if new tour comes from crossover? but what if > 1 tour per bin?
-  
-  # note: calling make_histogram with an empty list erases the previous histogram
+
+  # Helper method to draw a histogram of tour costs, called at the start of esearch.
+  # Note: rsearch calls make_histogram with an empty list to erase any previous histogram
+  # left by a call to esearch
   
   def make_histogram(pop)
     if @@drawing.histogram.length > 0
@@ -833,6 +1133,9 @@ module TSPLab
     @@recolor = false
   end
   
+  # After rebuild_population fills in the array again, it calls this method to
+  # resize the boxes to show fitness of tours and refills the grayed out boxes.
+  
   def update_histogram(pop)
     y = @@histogramOptions[:y]
     ymax = @@histogramOptions[:ymax]
@@ -852,17 +1155,8 @@ module TSPLab
     end
   end
   
-  def show_survivors(pop)
-    hist = @@drawing.histogram
-    return unless pop.length == hist.length
-    hist.each_with_index do |box, i|
-      box.fill = 'gray' if pop[i].op == :zap
-    end
-    @@recolor = true
-  end
-
-# Outdated attempt to show sequence of ancestors -- if revived, needs to
-# be updated for new Tk interface
+  # Outdated attempt to show sequence of ancestors -- if revived, needs to
+  # be updated for new Tk interface
  
   # def show_lineage(tour, userOptions = {} )
   #   options = @@lineageOptions.merge(userOptions)
@@ -887,6 +1181,13 @@ module TSPLab
   #   end
   #   return true
   # end
+
+  # def update_labels(a)
+  #   labels = @@drawing.labels
+  #   for i in 0...labels.length
+  #     labels[i].update(a[i])
+  #   end
+  # end
   
   # def test_setup
   #   m = Map.new(15)
@@ -911,7 +1212,6 @@ module TSPLab
 
   @@esearchOptions = {
     :popsize => 10,
-    :maxgen => 25,
     :profiles => {
       :mixed => [0.5, 0.25, 0.25],
       :random => [0.0, 0.0, 0.0],
@@ -944,14 +1244,36 @@ end # module TSPLab
 
 end # module RubyLabs
 
-
-module Enumerable
-  
 =begin rdoc
-  <tt>each_permtation</tt> is an iterator that makes all permutations of
-  a container in lexicographic order.
+  
+== Enumerable
+
+The code for the Traveling Salesman lab (tsplab.rb) extends the Enumerable module
+with a method that generates all permutations of a string, array, or any other object
+from a class the includes the Enumerable interface.
+
 =end
 
+module Enumerable
+  
+  # Iterate over all possible permutations of the objects in
+  # this container.  The permutations are generated in lexicographic order.
+  # 
+  # Example:
+  #   >> s = "ABCD"
+  #   => "ABCD"
+  #   >> s.each_permutation { |x| p x }
+  #   "ABCD"
+  #   "ABDC"
+  #   "ACBD"
+  #   "ACDB"
+  #   "ADBC"
+  #   ...
+  #   "DBCA"
+  #   "DCAB"
+  #   "DCBA"
+  #   => nil
+ 
   def each_permutation
     p = self.clone
     n = p.length