lib/picky/sources/base.rb in picky-0.12.3 vs lib/picky/sources/base.rb in picky-1.0.0

@@ -1,51 +1,65 @@
+# = Data Sources
+#
+# Currently, Picky offers the following Sources:
+# * CSV (comma – or other – separated file)
+# * Couch (CouchDB, key-value store)
+# * DB (Databases, foremost MySQL)
+# * Delicious (http://del.icio.us, online bookmarking service)
+# See also:
+# http://github.com/floere/picky/wiki/Sources-Configuration
+# 
+# Don't worry if your source isn't here. Adding your own is easy:
+# http://github.com/floere/picky/wiki/Contributing-sources
+#
 module Sources
   
   # Sources are where your data comes from.
   #
-  # Basically, a source has 1-3 methods.
-  # * harvest: Used by the indexer to gather data.
-  #            Yields an indexed_id (string or integer) and a string value.
+  # A source has 1 mandatory and 2 optional methods:
+  # * connect_backend (_optional_): called once for each type/category pair.
+  # * harvest: Used by the indexer to gather data. Yields an indexed_id (string or integer) and a string value.
+  # * take_snapshot (_optional_): called once for each type.
   #
-  # * connect_backend: Optional, called once for each type/category pair.
-  # * take_snapshot: Optional, called once for each type.
+  # This base class "implements" all these methods, but they don't do anything.
+  # Subclass this class <tt>class MySource < Base</tt> and override the methods in your source to do something.
+  #
   class Base
     
-    # Note: Default methods do nothing.
-    #
-    
     # Connect to the backend.
     #
-    # Note: Called once per index/category combination
-    #       before harvesting.
+    # Called once per index/category combination before harvesting.
     #
-    # For example, the db backend connects the db adapter.
+    # Examples:
+    # * The DB backend connects the DB adapter.
+    # * We open a connection to a key value store.
+    # * We open an file with data.
     #
     def connect_backend
       
     end
     
-    # Used to take a snapshot of your data if it is fast changing.
-    # e.g. in a database, a table based on the source's select
-    # statement is created.
+    # Called by the indexer when gathering data.
     #
-    # Note: Called before harvesting.
+    # Yields the data (id, text for id) for the given type and category.
     #
-    def take_snapshot type
-      
+    # When implementing or overriding your own,
+    # be sure to <tt>yield(id, text_for_id)</tt> (or <tt>block.call(id, text_for_id)</tt>)
+    # for the given type symbol and category symbol.
+    #
+    def harvest index, category # :yields: id, text_for_id
+      # This concrete implementation yields "nothing", override in subclasses.
     end
     
-    # Called by the indexer when gathering data.
+    # Used to take a snapshot of your data if it is fast changing.
     #
-    # Yields the data (id, text for id) for the given type and category.
+    # Called once for each type before harvesting.
     #
-    # When implementing or overriding your own,
-    # be sure to <tt>yield</tt> (or <tt>block.call</tt>) an id (as string or integer)
-    # and a corresponding text for the given type symbol and
-    # category symbol.
+    # Example:
+    # * In a DB source, a table based on the source's select statement is created.
     #
-    def harvest type, category
-      # yields nothing
+    def take_snapshot index
+      
     end
     
   end
   
 end
\ No newline at end of file