0
@@ -4,6 +4,17 @@ module Merb
0
     
0
     # The Behavior class is an interim route-building class that ties 
0
     # pattern-matching +conditions+ to output parameters, +params+.
0
+    # 
0
+    # ==== Parameters
0
+    # conditions <Hash>::
0
+    #   Conditions to be met for this behavior to take effect. 
0
+    # params <Hash>::
0
+    #   Hash describing the course action to take (Behavior) when the conditions
0
+    #   are a match. The values of the +params+ keys must be Strings.
0
+    # parent <Behavior,Nil>::
0
+    #   The parent of this Behavior (defaults to nil)
0
+    # 
0
+    # @public
0
     class Behavior
0
       attr_reader :placeholders, :conditions, :params
0
       attr_accessor :parent
0
@@ -53,13 +64,69 @@ module Merb
0
         @params.merge! params
0
       end
0
 
0
+      # add registers a new route.
0
+      # 
0
+      # ==== Parameters
0
+      # path <String, Regex>::
0
+      #   the url path to match
0
+      # params <Hash>::
0
+      #   To parameters the new routes maps to.
0
+      #
0
+      # ==== Returns
0
+      # Route:: The resulting Route from the +path+/+params+.
0
+      # 
0
+      # @public
0
       def add(path, params = {})
0
         match(path).to(params)
0
       end
0
       
0
-      # Matches a +path+ and any number of optional request methods as conditions of a route.
0
-      # Alternatively, +path+ can be a hash of conditions, in which case +conditions+ is ignored.
0
-      # Yields a new instance so that sub-matching may occur.
0
+      # Matches a +path+ and any number of optional request methods as 
0
+      # conditions of a route. Alternatively, +path+ can be a hash of conditions, 
0
+      # in which case +conditions+ ignored. 
0
+      #
0
+      # ==== Parameters
0
+      # 
0
+      # path <String, Regexp>:: 
0
+      #   When passing a string as +path+ you're defining a literal definition 
0
+      #   for your route. Using a colon, ex.: ":login", defines both a capture
0
+      #   and a named param.
0
+      #   When passing a regular expression you can define captures explicitly 
0
+      #   within the regular expression syntax.
0
+      #   +path+ is optional.
0
+      # conditions <Hash>::
0
+      #   This optional hash helps refine the settings for the route.
0
+      #   When combined with a block it can help keep your routes DRY
0
+      # &block <Proc>::
0
+      #   +match+ passes a new instance of a Behavior object into the optional 
0
+      #   block so that sub-matching and routes nesting may occur.
0
+      #   
0
+      # ==== Returns
0
+      # Behavior:: A new instance of Behavior with the specified +path+/+conditions+
0
+      #   
0
+      # +Tip+: When nesting always make sure the most inner sub-match registers
0
+      # a Route and doesn't just returns new Behaviors
0
+      #
0
+      # ==== For Example
0
+      #
0
+      #  # registers /foo/bar to controller => "foo", :action => "bar"
0
+      #  # and /foo/baz to controller => "foo", :action => "caz"
0
+      #  r.match "/foo", :controller => "foo" do |f| 
0
+      #    f.match("/bar").to(:action => "bar")
0
+      #    f.match("/baz").to(:action => "caz")
0
+      #  end 
0
+      #  
0
+      #
0
+      #  r.match "/foo", :controller => "foo" do |f| 
0
+      #    f.match("/bar", :action => "bar")
0
+      #    f.match("/baz", :action => "caz")
0
+      #  end => doesn't register any routes at all
0
+      # 
0
+      # +match+ also takes regular expressions
0
+      # 
0
+      #  r.match(%r[/account/([a-z]{4,6})]).to(:controller => "account", 
0
+      #          :action => "show", :id => "[1]")
0
+      # 
0
+      # @public
0
       def match(path = '', conditions = {}, &block)
0
         if path.is_a? Hash
0
           conditions = path
0
@@ -81,19 +148,30 @@ module Merb
0
         Route.new compiled_conditions, compiled_params, self, &conditional_block
0
       end
0
       
0
-      # Creates a Route from one or more Behavior objects, unless a +block+ is passed in.
0
-      # If a block is passed in, a Behavior object is yielded and further .to operations
0
-      # may be called in the block.  For example:
0
+      # Creates a Route from one or more Behavior objects, unless a +block+ is 
0
+      # passed in. 
0
       # 
0
-      #   r.match('/:controller/:id).to(:action => 'show')
0
+      # ==== Parameters
0
+      # 
0
+      #   params <hash>::
0
+      #     The parameters the route maps to.
0
+      #   &block <proc>::
0
+      #     Optional block. A new Behavior object is yielded and further .to 
0
+      #     operations may be called in the block.
0
       # 
0
-      # vs.
0
+      # ==== Returns
0
+      # Route :: It registers a new route and returns it.
0
+      # 
0
+      # ==== Examples
0
+      # 
0
+      #   r.match('/:controller/:id).to(:action => 'show')
0
       #   
0
       #   r.to :controller => 'simple' do |s|
0
       #     s.match('/test').to(:action => 'index')
0
       #     s.match('/other').to(:action => 'other')
0
       #   end
0
-      # 
0
+      #
0
+      # @public
0
       def to(params = {}, &block)
0
         if block_given?
0
           new_behavior = self.class.new({}, params, self)
0
@@ -104,27 +182,129 @@ module Merb
0
         end
0
       end
0
       
0
-      # Takes a block and stores it for defered conditional routes. 
0
-      # The block takes the +request+ object and the +params+ hash as parameters 
0
-      # and should return a hash of params.
0
-      # 
0
+      # Takes a block and stores it for deferred conditional routes. 
0
+      # The block takes the +request+ object and the +params+ hash as 
0
+      # parameters.
0
+      #
0
+      # ==== Parameters
0
+      #	params <Hash>::
0
+      #        parameters and conditions associated with this behavior
0
+      # &conditional_block <Proc>::
0
+      #		A block with the conditions to be met for the behavior to 
0
+      #		take effect
0
+      #
0
+      # ==== Returns
0
+      # Route :: The default route.
0
+      #	
0
+      # ==== Examples
0
       #   r.defer_to do |request, params|
0
-      #     params.merge :controller => 'here', :action => 'there'
0
+      #     params.merge :controller => 'here',
0
+      #                  :action => 'there' if request.xhr?
0
       #   end
0
-      # 
0
+      #
0
+      # @public
0
       def defer_to(params = {}, &conditional_block)
0
         Router.routes << (route = to_route(params, &conditional_block))
0
         route
0
       end
0
 
0
+      # Creates the most common routes /:controller/:action/:id.format when 
0
+      # called with no arguments.
0
+      # You can pass a hash or a block to add parameters or override the default 
0
+      # behavior.
0
+      # 
0
+      # ==== Parameters
0
+      # 
0
+      # params <Hash>:: This optional hash can be used to augment the default 
0
+      # settings
0
+      # &block <Proc>:: When passing a block a new behavior is yielded and 
0
+      # more refinement is possible. 
0
+      #
0
+      # ==== Returns
0
+      # Route :: the default route
0
+      # 
0
+      # ==== Examples
0
+      # 
0
+      #   # Passing an extra parameter "mode" to all matches
0
+      #   r.default_routes :mode => "default"
0
+      #   
0
+      #   # specifying exceptions within a block
0
+      #   r.default_routes do |nr|
0
+      #     nr.defer_to do |request, params|
0
+      #       nr.match(:protocol => "http://").to(:controller => "login", 
0
+      #         :action => "new") if request.env["REQUEST_URI"] =~ /\/private\//
0
+      #     end
0
+      #   end 
0
+      #
0
+      # @public  
0
       def default_routes(params = {}, &block)
0
         match(%r{/:controller(/:action(/:id)?)?(\.:format)?}).to(params, &block)
0
       end
0
 
0
+      # Creates a namespace for a route. This way you can have logical separation 
0
+      # to your routes.
0
+      # 
0
+      # ==== Parameters
0
+      # 
0
+      # name_or_path <String, Symbol>::
0
+      #   The name or path of the namespace.
0
+      # &block <Proc>::
0
+      #   A new Behavior instance is yielded in the block for nested resources.
0
+      #
0
+      # ==== Example
0
+      # 
0
+      #   r.namespace :admin do |admin|
0
+      #     admin.resources :accounts
0
+      #     admin.resource :email
0
+      #   end
0
+      #   
0
+      # @public
0
       def namespace(name_or_path, &block)
0
         yield self.class.new(:namespace => name_or_path.to_s)
0
       end
0
 
0
+      # Behavior#+resources+ is a route helper for defining a collection of
0
+      # RESTful resources.
0
+      # 
0
+      # ==== Parameters
0
+      # 
0
+      # name <String, Symbol>::
0
+      #   The name of the resources
0
+      # options <Hash>::
0
+      #   Ovverides and parameters to be associated with the route
0
+      # 
0
+      # ==== Options
0
+      # :namespace: defines the namespace for this route
0
+      # :name_prefix: a prefix for the named routes. If a namespace is passed
0
+      #   and there isn't a name prefix. The namespace will become the prefix.
0
+      # :controller: Specifies the controller for this route
0
+      # :collection: Specifies special settings for the collections routes
0
+      # :member: Specifies special settings and resources related to a specific 
0
+      #   member of this resource.
0
+      #
0
+      # ==== Returns
0
+      # Array<Routes> :: an Array of Routes which will define the specified
0
+      # RESTful collection of resources
0
+      # 
0
+      # ==== Examples
0
+      # 
0
+      #  r.resources :posts # will result in the tipical RESTful crud
0
+      #   
0
+      #   GET     /posts/?(\.:format)?      :action => "index"
0
+      #   GET     /posts/index(\.:format)?  :action => "index"
0
+      #   GET     /posts/new                :action => "new"
0
+      #   POST    /posts/?(\.:format)?,     :action => "create"
0
+      #   GET     /posts/:id(\.:format)?    :action => "show"
0
+      #   GET     /posts/:id[;/]edit        :action => "edit"
0
+      #   PUT     /posts/:id(\.:format)?    :action => "update"
0
+      #   DELETE  /posts/:id(\.:format)?    :action => "destroy"
0
+      # 
0
+      #  # Nesting resources
0
+      #  r.resources :posts do |posts|
0
+      #    posts.resources :comments
0
+      #  end
0
+      #
0
+      # @public  
0
       def resources(name, options = {})
0
         namespace = options[:namespace] || merged_params[:namespace] || conditions[:namespace]
0
         
0
@@ -185,6 +365,43 @@ module Merb
0
         routes
0
       end
0
 
0
+      # Behavior#+resource+ is a route helper for defining a single RESTful resource.
0
+      # 
0
+      # ==== Parameters
0
+      # 
0
+      # name <String, Symbol>::
0
+      #   The name of the resource
0
+      # options <Hash>::
0
+      #   Ovverides and parameters to be associated with the route
0
+      # 
0
+      # ==== Options
0
+      # :namespace: defines the namespace for this route
0
+      # :name_prefix: a prefix for the named routes. If a namespace is passed
0
+      #   and there isn't a name prefix. The namespace will become the prefix.
0
+      # :controller: Specifies the controller for this route
0
+      # 
0
+      # ==== Returns
0
+      # Array<Routes> :: an Array of Routes which define a RESTful single resource
0
+      # 
0
+      # ==== Examples
0
+      # 
0
+      #  r.resources :account # will result in the tipical RESTful crud
0
+      #   
0
+      #   GET     /account/new                :action => "new"
0
+      #   POST    /account/?(\.:format)?,     :action => "create"
0
+      #   GET     /account/(\.:format)?       :action => "show"
0
+      #   GET     /account/[;/]edit           :action => "edit"
0
+      #   PUT     /account/(\.:format)?       :action => "update"
0
+      #   DELETE  /account/(\.:format)?       :action => "destroy"
0
+      #
0
+      # You can optionally pass :namespace and :controller to refine the routing
0
+      # or pass a block to nest resources.
0
+      # 
0
+      #  r.resource :account, :namespace => "admin" do |account|
0
+      #    account.resources :preferences, :controller => "settings"
0
+      #  end
0
+      # 
0
+      # @public  
0
       def resource(name, options = {})
0
         namespace  = options[:namespace] || merged_params[:namespace] || conditions[:namespace]        
0
         match_path = namespace ? "/#{namespace}/#{name}" : "/#{name}"