source.rb in wvanbergen-request-log-analyzer-1.1.4

- old
+ new

@@ -1,14 +1,29 @@
+# The RequestLogAnalyzer::Source module contains all functionality that loads requests from a given source
+# and feed them to the pipeline for further processing. The requests (see RequestLogAnalyzer::Request) that
+# will be parsed from a source, will be piped throug filters (see RequestLogAnalyzer::Filter) and are then 
+# fed to an aggregator (see RequestLogAnalyzer::Aggregator). The source instance is thus the beginning of 
+# the RequestLogAnalyzer chain.
+#
+# - The base class for all sources is RequestLogAnalyzer::Source::Base. All source classes should inherit from this class.
+# - Currently, RequestLogAnalyzer::Source::LogParser is the only implemented source.
 module RequestLogAnalyzer::Source
 
+  # Loads constants that reside in the RequestLogAnalyzer::Source namespace. This function uses
+  # RequestLogAnalyzer::load_default_class_file to load the file in which the constant is declared.
+  # <tt>const</tt>:: The constant to load in the RequestLogAnalyzer::Source namespace.
   def self.const_missing(const)
     RequestLogAnalyzer::load_default_class_file(self, const)
   end
   
-  # Base Source class. All other sources inherit from this class
+  # The base Source class. All other sources should inherit from this class.
+  #
+  # A source implememtation should at least implement the each_request method, which should yield
+  # RequestLogAnalyzer::Request instances that will be fed through the pipleine.
   class Base
     
+    # Make the Spurce instance aware of the current file format
     include RequestLogAnalyzer::FileFormat::Awareness
 
     # A hash of options
     attr_reader :options
 
@@ -22,26 +37,32 @@
     attr_reader :parsed_requests
 
     # The number of skipped lines because of warnings
     attr_reader :skipped_lines
 
-    # Base source class used to filter input requests.
-
-    # Initializer
-    # <tt>format</tt> The file format
-    # <tt>options</tt> Are passed to the filters.
+    # Initializer, which will register the file format and save any options given as a hash.
+    # <tt>format</tt>:: The file format instance
+    # <tt>options</tt>:: A hash of options that can be used by a specific Source implementation
     def initialize(format, options = {})
       @options    = options
       register_file_format(format)
     end
     
+    # The prepare method is called before the RequestLogAnalyzer::Source::Base#each_request method is called.
+    # Use this method to implement any initialization that should occur before this source can produce Request
+    # instances.
     def prepare
     end
     
-    def each_request(&block)
+    # This function is called to actually produce the requests that will be send into the pipeline. 
+    # The implementation should yield instances of RequestLogAnalyzer::Request.
+    # <tt>options</tt>:: A Hash of options that can be used in the implementation.
+    def each_request(options = {}, &block) # :yields: request
       return true
     end
 
+    # This function is called after RequestLogAnalyzer::Source::Base#each_request finished. Any code to
+    # wrap up, free resources, etc. can be put in this method.
     def finalize
     end
 
   end
 end
\ No newline at end of file