0
@@ -1,6 +1,6 @@
0
 module Waves
0
 
0
-  module Dispatchers #:nodoc:
0
+  module Dispatchers
0
 
0
     # A NotFoundError means what you think it means.  The dispatchers included with Waves do not
0
     # natively intercept this exception.  Instead an exception handler must be registered in the application
0
@@ -21,16 +21,15 @@ module Waves
0
       end
0
     end
0
 
0
-    # Waves::Dispatchers::Base provides the basic request processing structure.
0
-    # All other Waves dispatchers should inherit from it.  It creates a Waves request, 
0
-    # determines whether to enclose the request processing in a mutex, benchmarks it, 
0
-    # logs it, and handles common exceptions and redirects. Derived classes need only 
0
+    # Waves::Dispatchers::Base provides the basic request processing structure for a Rack application.
0
+    # It creates a Waves request, determines whether to enclose the request processing in a mutex
0
+    # benchmarks it, logs it, and handles redirects. Derived classes need only 
0
     # process the request within the +safe+ method, which must take a Waves::Request and return a Waves::Response.
0
 
0
     class Base
0
 
0
       # As with any Rack application, a Waves dispatcher must provide a call method
0
-      # that takes an +env+ parameter.
0
+      # that takes an +env+ hash.
0
       def call( env )
0
         if Waves.config.synchronize?
0
           Waves::Runtime.instance.synchronize { _call( env ) }

0
@@ -1,33 +1,41 @@
0
 module Waves
0
 
0
+  # A Dispatcher in Waves is the interface between the outside world and the Waves application code.  
0
+  # Dispatchers that inherit from Waves::Dispatchers::Base are "Rack applications", to use the 
0
+  # terminology of the Rack specification.
0
+  # 
0
+  # Rack turns an incoming HTTP request into a environment hash and passes it as an argument to 
0
+  # the Dispatcher's +call+ method.  The dispatcher must return an array containing the status code, 
0
+  # response headers, and response body.  Waves::Dispatchers::Base provides a basic structure so that
0
+  # subclassed dispatchers need only implement the +safe+ method, which operates on a Waves::Request
0
+  # and returns a Waves::Response.  The +call+ method implemented by the Base dispatcher formats the 
0
+  # return value required by the Rack specification.
0
+  # 
0
+  # You can write your own dispatcher and use it in the Rack::Builder block in your configuration
0
+  # files. By default, the configurations use the Default dispatcher:
0
+  #
0
+  #   application do
0
+  #     use Rack::ShowExceptions
0
+  #     run Waves::Dispatchers::Default.new
0
+  #   end
0
+  #
0
   module Dispatchers
0
 
0
     #
0
-    # Waves::Dispatchers::Default matches requests against an application's mappings to 
0
-    # determine what main action to take, as well as what before, after, always, and exception-handling
0
-    # blocks must run.
0
-    #
0
-    # The default dispatcher also attempts to set the content type based on the
0
-    # file extension used in the request URL. It does this using the class defined in
0
-    # the current configuration's +mime_types+ attribute, which defaults to Mongrel's
0
-    # MIME type handler.
0
-    #
0
-    # You can write your own dispatcher and use it in your application's configuration
0
-    # file. By default, they use the default dispatcher, like this:
0
-    #
0
-    #   application do
0
-    #     use Rack::ShowExceptions
0
-    #     run Waves::Dispatchers::Default.new
0
-    #   end
0
+    # Waves::Dispatchers::Default processes a Waves::Request and returns a Waves::Response as follows:
0
     #
0
+    # 1. reload any reloadable constants if Waves.debug? is true
0
+    # 1. determine the content type using the mime-type indicated by the request URL's file extension
0
+    # 1. evaluate all :before mappings that match the request
0
+    # 1. evaluate the first :action mapping that matches the request.  If nothing matches, raise a NotFoundError
0
+    # 1. evalute all :after mappings that match the request
0
+    # 1. if any exceptions were raised, evaluate the first 
0
+    #    exception handler that matches the request.  If no handlers match the request, re-raise the exception.
0
+    # 1. evaluate every :always mapping that matches the request.  Log any exceptions and continues.
0
 
0
     class Default < Base
0
 
0
-      # Takes a Waves::Request and returns a Waves::Response, reloading the reloadable application constants
0
-      # if Waves.debug? is true.  +safe+ processes the request by searching the application mappings for an action,
0
-      # as well as any matching :before and :after filters.  If an exception is raised during the processing, 
0
-      # +safe+ looks for an  exception handler in the mappings.  After processing the filters, action, and any 
0
-      # exception handlers, the method evaluates any :always filters that matched the request. 
0
+      # Takes a Waves::Request and returns a Waves::Response    
0
       def safe( request  )
0
 
0
         response = request.response

0
@@ -1,6 +1,8 @@
0
 module Waves
0
   module Layers
0
     module Inflect
0
+      
0
+      # Adds plural/singular methods for English to String
0
       module English
0
         
0
         def self.included(app)

0
@@ -3,7 +3,7 @@ module Waves
0
     module Inflect
0
       module English
0
         # Extends Waves::Inflect::InflectorMethods
0
-        module Rules
0
+        module Rules 
0
         
0
           extend Waves::Inflect::InflectorMethods
0
 

0
@@ -2,8 +2,9 @@ module Waves
0
   module Layers
0
     module ORM # :nodoc:
0
       
0
-      # Sets up the Sequel connection and configures AutoCode on Models, so that constants in that
0
-      # namespace get loaded from file or created as subclasses of Models::Default
0
+      # The Sequel ORM layer sets up the Sequel connection and configures AutoCode on Models, so that constants in that
0
+      # namespace get loaded from file or created as subclasses of Models::Default.  The dataset for models is set to the
0
+      # snakecased version of the model's class name.
0
       module Sequel
0
 
0
         # On inclusion, this module:

0
@@ -1,5 +1,45 @@
0
 module Waves
0
 
0
+  # = Mappings
0
+  #
0
+  # Mappings are the heart of Waves, the system whereby the madding crowd of slovenly requests are
0
+  # sorted, segregated, cleaned and dressed, put on their best behavior, and shunted through as complex 
0
+  # a series of filters as you, the web developer, could wish for.
0
+  # 
0
+  # More simply, mappings are the routes which determine how a request will be handled.  Each mapping registers
0
+  # an action against a set of constraints, and a request must satisfy these constraints for the action to be usable.
0
+  # You can describe a Pattern that the URI path must match, or specify a domain, the URL scheme, 
0
+  # or HTTP headers.  How the mappings are used is determined by the particular Dispatcher in operation.
0
+  # 
0
+  # There are three basic types of mapping:  responses, filters, and exception handlers
0
+  #
0
+  # == Responses
0
+  # 
0
+  # A response mapping provides the primary action in answer to a HTTP request.  That is, the return value of an action
0
+  # is written to the HTTP response body.  The default dispatcher runs only the first response mapping it finds 
0
+  # that matches the request.
0
+  #
0
+  # == Filters
0
+  # 
0
+  # The filter mappings are :before, :after, and :always.  Filters may be used for side effects
0
+  # or to contribute to the response.  The return value of a filter is discarded, so filters must manipulate the 
0
+  # response object directly to effect any changes.  
0
+  #
0
+  # The default dispatcher runs all :before mappings that match the request before searching for a response mapping.
0
+  # After evaluating the response action, the dispatcher runs all :after filters that match the request.  Finally, after
0
+  # processing any exceptions that were thrown by the before, response, and after actions, the dispatcher runs 
0
+  # every :always mapping that matches the request.  Thus the :always filters function like +ensure+ in Ruby.
0
+  #
0
+  # == Exception handlers
0
+  # 
0
+  # Handler mappings take an exception class as a constraint, in addition to any of the other possible constraints.
0
+  # The default dispatcher uses an exception handler, if it can find one, to process exceptions thrown by 
0
+  # the before, response, and after actions.
0
+  # 
0
+  # = Constraints
0
+  #
0
+  # 
0
+  
0
   module Mapping
0
     
0
     include Functor::Method

0
@@ -4,10 +4,15 @@ module Waves
0
 
0
   module Mapping
0
     
0
+    # In a Waves mapping, the Pattern is the structure used to match the path of the request URI.
0
+    # 
0
+    # A Pattern consists of an array where each element corresponds to a path component in a request URI.
0
+    
0
     class Pattern
0
       
0
       include Functor::Method
0
       
0
+      # Takes an options hash.  Currently uses options[:path] only.
0
       def initialize( options ) ; @pattern = options[ :path ] ; end
0
       
0
       # A pattern-matching method provided by the power of Functor.  Most external calls to +match+