From 147f927f84e6eebd21935946f5b1950aa492b395 Mon Sep 17 00:00:00 2001
From: Adam Sanderson <netghost@gmail.com>
Date: Wed, 29 Dec 2010 15:39:11 -0700
Subject: [PATCH] Fleshing out the documentation

---
 lib/qwandry/flat_repository.rb    | 11 ++++++++---
 lib/qwandry/library_repository.rb | 15 ++++++++++-----
 lib/qwandry/repository.rb         | 17 +++++++++++++----
 3 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/lib/qwandry/flat_repository.rb b/lib/qwandry/flat_repository.rb
index 4039a05..59038d3 100644
--- a/lib/qwandry/flat_repository.rb
+++ b/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|
diff --git a/lib/qwandry/library_repository.rb b/lib/qwandry/library_repository.rb
index a736502..9f010eb 100644
--- a/lib/qwandry/library_repository.rb
+++ b/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|
diff --git a/lib/qwandry/repository.rb b/lib/qwandry/repository.rb
index eb16b3b..2e7947d 100644
--- a/lib/qwandry/repository.rb
+++ b/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}