Fleshing out the documentation

lib/qwandry/flat_repository.rb

@@ -1,8 +1,13 @@
 module Qwandry
-  # Directories look like:
-  #       ./lib-0.1
-  #       ./lib-0.2
+  # The FlatRepository assumes that each file or directory in the search path
+  # is a stand alone Package.  For instance:
+  # 
+  #     rails-2.3.2
+  #     rails-3.0.1
+  #     thin
+  # 
   class FlatRepository < Qwandry::Repository
+    # Returns a Package for each matching file or directory.
     def scan(pattern)
       results = []
       all_paths.select do |path|

lib/qwandry/library_repository.rb

@@ -1,10 +1,15 @@
 module Qwandry
-  # Directories look like:
-  #     lib1.rb
-  #     lib1/...
-  #     lib2.py
-  #     lib2/...
+  # The LibraryRepository assumes that the search path contains files in the root mixed with
+  # directories of the same name which should be opened together.  Ruby's date library is a good
+  # example of this:
+  # 
+  #     date.rb
+  #     date/
+  # 
   class LibraryRepository < Qwandry::Repository
+    
+    # Returns Packages that may contain one or more paths if there are similar
+    # root level files that should be bundled together.
     def scan(pattern)
       results = Hash.new{|h,k| h[k] = package(k)}
       all_paths.select do |path|

lib/qwandry/repository.rb

@@ -1,20 +1,27 @@
 module Qwandry
+  # A Repository's primary responsibility is to return a set of Packages that
+  # match the search criteria used in Repository#scan.
+  # 
+  # Subclasses are expected 
   class Repository
     attr_reader :name
     attr_reader :path
     attr_reader :options
-  
+    
+    # Creates a Repository with a give name, search path, and options.
     def initialize(name, path, options={})
       @name = name
       @path = path.chomp('/')
       @options = options
-      
     end
     
+    # Given a name, scan should an array with 0 or more Packages matching the
+    # name.
     def scan(name)
-      []
+      raise NotImplementedError, "Repositories must return an Array of matching packages."
     end
     
+    # Returns all paths that should be tested by Qwandry#scan.
     def all_paths
       paths = Dir["#{@path}/*"]
       paths = paths.select(&matcher(options[:accept])) if options[:accept]
@@ -22,11 +29,13 @@ module Qwandry
       paths
     end
   
+    private
+    # Helper for assembling a new package which may be launched by the Launcher
     def package(name, paths=[])
       Package.new(name, paths, self)
     end
     
-    private
+    # Helper for generating a predicate methods
     def matcher(pattern)
       case pattern
       when Regexp then lambda{|p| p =~ pattern}