Merge branch 'master' of git://github.com/lifo/docrails

4 files changed, 249 insertions, 99 deletions

diff --git a/actionpack/lib/action_controller/metal.rb b/actionpack/lib/action_controller/metal.rb
index 3df3c341bb..032769a5c6 100644
--- a/actionpack/lib/action_controller/metal.rb
+++ b/actionpack/lib/action_controller/metal.rb
@@ -43,12 +43,62 @@ module ActionController
     end
   end
 
-  # Provides a way to get a valid Rack application from a controller.
+  # ActionController::Metal is the simplest possible controller, providing a
+  # valid Rack interface without the additional niceties provided by
+  # ActionController::Base.
+  #
+  # A sample Metal controller might look like this:
+  #
+  #   class HelloController < ActionController::Metal
+  #     def index
+  #       self.response_body = "Hello World!"
+  #     end
+  #   end
+  #
+  # And then to route requests to your Metal controller, you would add
+  # something like this to <tt>config/routes.rb</tt>:
+  #
+  #   match '/hello', :to => HelloController.action(:index),
+  #     :as => 'hello'
+  #
+  # The action method returns a valid Rack application for the \Rails
+  # router to dispatch to.
+  #
+  # == Rendering Helpers
+  #
+  # ActionController::Metal by default provides no utilities for rendering
+  # views, partials, or other responses aside from explicitly calling of
+  # response_body=, content_type=, and status=. To
+  # add the render helpers you're used to having in a normal controller, you
+  # can do the following:
+  #
+  #   class HelloController < ActionController::Metal
+  #     include ActionController::Rendering
+  #     append_view_path Rails.root + "app/views"
+  #
+  #     def index
+  #       render "hello/index"
+  #     end
+  #   end
+  #
+  # == Redirection Helpers
+  #
+  # To add redirection helpers to your Metal controller, do the following:
+  #
+  #   class HelloController < ActionController::Metal
+  #     include ActionController::Redirecting
+  #
+  #     def index
+  #       redirect_to root_url
+  #     end
+  #   end
+  #
+  # == Other Helpers
+  #
+  # You can refer to the modules defined in ActionController to see
+  # the other features in ActionController::Base that you can bring
+  # into your Metal controller.
   #
-  # In AbstractController, dispatching is triggered directly by calling #process on a new controller.
-  # <tt>ActionController::Metal</tt> provides an <tt>action</tt> method that returns a valid Rack application for a
-  # given action. Other rack builders, such as Rack::Builder, Rack::URLMap, and the \Rails router,
-  # can dispatch directly to actions returned by controllers in your application.
   class Metal < AbstractController::Base
     abstract!
 
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb
index 8810227a59..43fd93adf6 100644
--- a/actionpack/lib/action_dispatch/routing.rb
+++ b/actionpack/lib/action_dispatch/routing.rb
@@ -56,6 +56,18 @@ module ActionDispatch
   #     resources :posts, :comments
   #   end
   #
+  # Alternately, you can add prefixes to your path without using a separate
+  # directory by using +scope+. +scope+ takes additional options which
+  # apply to all enclosed routes.
+  #
+  #   scope :path => "/cpanel", :as => 'admin' do
+  #     resources :posts, :comments
+  #   end
+  #
+  # For more, see <tt>Routing::Mapper::Resources#resources</tt>,
+  # <tt>Routing::Mapper::Scoping#namespace</tt>, and
+  # <tt>Routing::Mapper::Scoping#scope</tt>.
+  #
   # == Named routes
   #
   # Routes can be named by passing an <tt>:as</tt> option,
diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index f65a294eca..b28b68ad83 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -256,15 +256,94 @@ module ActionDispatch
           match '/', options.reverse_merge(:as => :root)
         end
 
-        # When you set up a regular route, you supply a series of symbols that
-        # Rails maps to parts of an incoming HTTP request.
+        # Matches a pattern to one or more urls. Any symbols in a pattern are
+        # interpreted as url parameters:
         #
-        #   match ':controller/:action/:id/:user_id'
+        #   # sets parameters :controller, :action and :id
+        #   match ':controller/:action/:id'
         #
-        # Two of these symbols are special: :controller maps to the name of a
-        # controller in your application, and :action maps to the name of an
-        # action within that controller. Anything other than :controller or
-        # :action will be available to the action as part of params.
+        # Two of these symbols are special: <tt>:controller</tt> maps to the
+        # controller name and <tt>:action</tt> to the action name within that
+        # controller. Anything other than <tt>:controller</tt> or
+        # <tt>:action</tt> will be available to the action as part of +params+.
+        # If a pattern does not have :controller and :action symbols, then they
+        # must be set in options or shorthand. For example:
+        #
+        #   match 'photos/:id' => 'photos#show'
+        #   match 'photos/:id', :to => 'photos#show'
+        #   match 'photos/:id', :controller => 'photos', :action => 'show'
+        #
+        # === Supported options
+        #
+        # [:controller]
+        #   The route's controller.
+        #
+        # [:action]
+        #   The route's action.
+        #
+        # [:path]
+        #   The path prefix for the routes.
+        #
+        # [:module]
+        #   The namespace for :controller.
+        #
+        #     match 'path' => 'c#a', :module => 'sekret', :controller => 'posts'
+        #     #=> Sekret::PostsController
+        #
+        #   See <tt>Scoping#namespace</tt> for its scope equivalent.
+        #
+        # [:as]
+        #   The name used to generate routing helpers.
+        #
+        # [:via]
+        #   Allowed HTTP verb(s) for route.
+        #
+        #      match 'path' => 'c#a', :via => :get
+        #      match 'path' => 'c#a', :via => [:get, :post]
+        #
+        # [:to]
+        #   Shorthand for specifying :controller and :action.
+        #
+        #      match 'path' => 'c#a', :to => 'controller#action'
+        #
+        # [:on]
+        #   Shorthand for wrapping routes in a specific RESTful context. Valid
+        #   values are :member, :collection, and :new.  Only use within
+        #   <tt>resource(s)</tt> block. For example:
+        #
+        #      resource :bar do
+        #        match 'foo' => 'c#a', :on => :member, :via => [:get, :post]
+        #      end
+        #
+        #   Is equivalent to:
+        #
+        #      resource :bar do
+        #        member do
+        #          match 'foo' => 'c#a', :via => [:get, :post]
+        #        end
+        #      end
+        #
+        # [:constraints]
+        #   Constrains parameters with a hash of regular expressions or an
+        #   object that responds to #matches?
+        #
+        #     match 'path/:id', :constraints => { :id => /[A-Z]\d{5}/ }
+        #
+        #     class Blacklist
+        #       def matches?(request) request.remote_ip == '1.2.3.4' end
+        #     end
+        #     match 'path' => 'c#a', :constraints => Blacklist.new
+        #
+        #   See <tt>Scoping#constraints</tt> for more examples with its scope
+        #   equivalent.
+        #
+        # [:defaults]
+        #   Sets defaults for parameters
+        #
+        #     # Sets params[:format] to 'jpg' by default
+        #     match 'path' => 'c#a', :defaults => { :format => 'jpg' }
+        #
+        #   See <tt>Scoping#defaults</tt> for its scope equivalent.
         def match(path, options=nil)
           mapping = Mapping.new(@set, @scope, path, options || {}).to_route
           @set.add_route(*mapping)
@@ -349,7 +428,7 @@ module ActionDispatch
 
       module HttpHelpers
         # Define a route that only recognizes HTTP GET.
-        # For supported arguments, see +match+.
+        # For supported arguments, see <tt>Base#match</tt>.
         #
         # Example:
         #
@@ -359,7 +438,7 @@ module ActionDispatch
         end
 
         # Define a route that only recognizes HTTP POST.
-        # For supported arguments, see +match+.
+        # For supported arguments, see <tt>Base#match</tt>.
         #
         # Example:
         #
@@ -369,7 +448,7 @@ module ActionDispatch
         end
 
         # Define a route that only recognizes HTTP PUT.
-        # For supported arguments, see +match+.
+        # For supported arguments, see <tt>Base#match</tt>.
         #
         # Example:
         #
@@ -379,7 +458,7 @@ module ActionDispatch
         end
 
         # Define a route that only recognizes HTTP PUT.
-        # For supported arguments, see +match+.
+        # For supported arguments, see <tt>Base#match</tt>.
         #
         # Example:
         #
@@ -458,7 +537,7 @@ module ActionDispatch
           super
         end
 
-        # Used to scope a set of routes to particular constraints.
+        # Scopes a set of routes to the given default options.
         #
         # Take the following route definition as an example:
         #
@@ -471,50 +550,25 @@ module ActionDispatch
         # rather than /accounts/rails/projects/2.
         #
         # === Supported options
-        # [:module]
-        #   If you want to route /posts (without the prefix /admin) to
-        #   Admin::PostsController, you could use
-        #
-        #     scope :module => "admin" do
-        #       resources :posts
-        #     end
-        #
-        # [:path]
-        #   If you want to prefix the route, you could use
-        #
-        #     scope :path => "/admin" do
-        #       resources :posts
-        #     end
         #
-        #   This will prefix all of the +posts+ resource's requests with '/admin'
+        # Takes same options as <tt>Base#match</tt> and <tt>Resources#resources</tt>.
         #
-        # [:as]
-        #  Prefixes the routing helpers in this scope with the specified label.
-        #
-        #    scope :as => "sekret" do
-        #      resources :posts
-        #    end
-        #
-        # Helpers such as +posts_path+ will now be +sekret_posts_path+
-        #
-        # [:shallow_path]
-        #
-        #   Prefixes nested shallow routes with the specified path.
+        # === Examples
         #
-        #   scope :shallow_path => "sekret" do
-        #     resources :posts do
-        #       resources :comments, :shallow => true
-        #     end
+        #   # route /posts (without the prefix /admin) to Admin::PostsController
+        #   scope :module => "admin" do
+        #     resources :posts
+        #   end
         #
-        #   The +comments+ resource here will have the following routes generated for it:
+        #   # prefix the posts resource's requests with '/admin'
+        #   scope :path => "/admin" do
+        #     resources :posts
+        #   end
         #
-        #     post_comments    GET    /sekret/posts/:post_id/comments(.:format)
-        #     post_comments    POST   /sekret/posts/:post_id/comments(.:format)
-        #     new_post_comment GET    /sekret/posts/:post_id/comments/new(.:format)
-        #     edit_comment     GET    /sekret/comments/:id/edit(.:format)
-        #     comment          GET    /sekret/comments/:id(.:format)
-        #     comment          PUT    /sekret/comments/:id(.:format)
-        #     comment          DELETE /sekret/comments/:id(.:format)
+        #   # prefix the routing helper name: sekret_posts_path instead of posts_path
+        #   scope :as => "sekret" do
+        #     resources :posts
+        #   end
         def scope(*args)
           options = args.extract_options!
           options = options.dup
@@ -577,43 +631,31 @@ module ActionDispatch
         #        admin_post GET    /admin/posts/:id(.:format)      {:action=>"show", :controller=>"admin/posts"}
         #        admin_post PUT    /admin/posts/:id(.:format)      {:action=>"update", :controller=>"admin/posts"}
         #        admin_post DELETE /admin/posts/:id(.:format)      {:action=>"destroy", :controller=>"admin/posts"}
-        # === Supported options
-        #
-        # The +:path+, +:as+, +:module+, +:shallow_path+ and +:shallow_prefix+ options all default to the name of the namespace.
-        #
-        # [:path]
-        #   The path prefix for the routes.
         #
-        #     namespace :admin, :path => "sekret" do
-        #       resources :posts
-        #     end
-        #
-        #   All routes for the above +resources+ will be accessible through +/sekret/posts+, rather than +/admin/posts+
-        #
-        # [:module]
-        #   The namespace for the controllers.
+        # === Supported options
         #
-        #     namespace :admin, :module => "sekret" do
-        #       resources :posts
-        #     end
+        # The +:path+, +:as+, +:module+, +:shallow_path+ and +:shallow_prefix+
+        # options all default to the name of the namespace.
         #
-        #   The +PostsController+ here should go in the +Sekret+ namespace and so it should be defined like this:
+        # For options, see <tt>Base#match</tt>. For +:shallow_path+ option, see
+        # <tt>Resources#resources</tt>.
         #
-        #     class Sekret::PostsController < ApplicationController
-        #       # code go here
-        #     end
+        # === Examples
         #
-        # [:as]
-        #   Changes the name used in routing helpers for this namespace.
-        #
-        #     namespace :admin, :as => "sekret" do
-        #       resources :posts
-        #     end
+        #   # accessible through /sekret/posts rather than /admin/posts
+        #   namespace :admin, :path => "sekret" do
+        #     resources :posts
+        #   end
         #
-        # Routing helpers such as +admin_posts_path+ will now be +sekret_posts_path+.
+        #   # maps to Sekret::PostsController rather than Admin::PostsController
+        #   namespace :admin, :module => "sekret" do
+        #     resources :posts
+        #   end
         #
-        # [:shallow_path]
-        #   See the +scope+ method.
+        #   # generates sekret_posts_path rather than admin_posts_path
+        #   namespace :admin, :as => "sekret" do
+        #     resources :posts
+        #   end
         def namespace(path, options = {})
           path = path.to_s
           options = { :path => path, :as => path, :module => path,
@@ -680,9 +722,9 @@ module ActionDispatch
         end
 
         # Allows you to set default parameters for a route, such as this:
-        # defaults :id => 'home' do
-        #   match 'scoped_pages/(:id)', :to => 'pages#show'
-        # end
+        #   defaults :id => 'home' do
+        #     match 'scoped_pages/(:id)', :to => 'pages#show'
+        #   end
         # Using this, the +:id+ parameter here will default to 'home'.
         def defaults(defaults = {})
           scope(:defaults => defaults) { yield }
@@ -827,7 +869,8 @@ module ActionDispatch
 
           alias :member_name :singular
 
-          # Checks for uncountable plurals, and appends "_index" if they're.
+          # Checks for uncountable plurals, and appends "_index" if the plural 
+          # and singular form are the same.
           def collection_name
             singular == plural ? "#{plural}_index" : plural
           end
@@ -906,6 +949,9 @@ module ActionDispatch
         #   GET     /geocoder/edit
         #   PUT     /geocoder
         #   DELETE  /geocoder
+        #
+        # === Supported options
+        # Takes same options as +resources+.
         def resource(*resources, &block)
           options = resources.extract_options!
 
@@ -968,6 +1014,8 @@ module ActionDispatch
         #   DELETE  /photos/:id/comments/:id
         #
         # === Supported options
+        # Takes same options as <tt>Base#match</tt> as well as:
+        #
         # [:path_names]
         #   Allows you to change the paths of the seven default actions.
         #   Paths not specified are not changed.
@@ -976,20 +1024,60 @@ module ActionDispatch
         #
         #   The above example will now change /posts/new to /posts/brand_new
         #
-        # [:module]
-        #   Set the module where the controller can be found. Defaults to nothing.
+        # [:only]
+        #   Only generate routes for the given actions.
         #
-        #     resources :posts, :module => "admin"
+        #     resources :cows, :only => :show
+        #     resources :cows, :only => [:show, :index]
         #
-        #   All requests to the posts resources will now go to +Admin::PostsController+.
+        # [:except]
+        #   Generate all routes except for the given actions.
         #
-        # [:path]
+        #     resources :cows, :except => :show
+        #     resources :cows, :except => [:show, :index]
+        #
+        # [:shallow]
+        #   Generates shallow routes for nested resource(s). When placed on a parent resource,
+        #   generates shallow routes for all nested resources.
+        #
+        #     resources :posts, :shallow => true do
+        #       resources :comments
+        #     end
+        #
+        #   Is the same as:
+        #
+        #     resources :posts do
+        #       resources :comments
+        #     end
+        #     resources :comments
+        #
+        # [:shallow_path]
+        #   Prefixes nested shallow routes with the specified path.
+        #
+        #   scope :shallow_path => "sekret" do
+        #     resources :posts do
+        #       resources :comments, :shallow => true
+        #     end
+        #   end
+        #
+        #   The +comments+ resource here will have the following routes generated for it:
+        #
+        #     post_comments    GET    /sekret/posts/:post_id/comments(.:format)
+        #     post_comments    POST   /sekret/posts/:post_id/comments(.:format)
+        #     new_post_comment GET    /sekret/posts/:post_id/comments/new(.:format)
+        #     edit_comment     GET    /sekret/comments/:id/edit(.:format)
+        #     comment          GET    /sekret/comments/:id(.:format)
+        #     comment          PUT    /sekret/comments/:id(.:format)
+        #     comment          DELETE /sekret/comments/:id(.:format)
+        #
+        # === Examples
         #
-        #  Set a path prefix for this resource.
+        #   # routes call Admin::PostsController
+        #   resources :posts, :module => "admin"
         #
-        #     resources :posts, :path => "admin"
+        #   # resource actions are at /admin/posts.
+        #   resources :posts, :path => "admin"
         #
-        #  All actions for this resource will now be at +/admin/posts+.
         def resources(*resources, &block)
           options = resources.extract_options!
 
diff --git a/actionpack/lib/action_dispatch/testing/assertions/response.rb b/actionpack/lib/action_dispatch/testing/assertions/response.rb
index 1558c3ae05..77a15f3e97 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/response.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/response.rb
@@ -20,7 +20,7 @@ module ActionDispatch
       #
       # You can also pass an explicit status number like <tt>assert_response(501)</tt>
       # or its symbolic equivalent <tt>assert_response(:not_implemented)</tt>.
-      # See ActionDispatch::StatusCodes for a full list.
+      # See Rack::Utils::SYMBOL_TO_STATUS_CODE for a full list.
       #
       # ==== Examples
       #