Make rdoc match current API

Signed-off-by: NMikel Lindsaar <raasdnil@gmail.com>

actionpack/lib/action_dispatch/routing.rb

@@ -9,17 +9,18 @@ module ActionDispatch
   # mod_rewrite rules. Best of all, Rails' Routing works with any web server.
   # Routes are defined in <tt>config/routes.rb</tt>.
   #
-  # Consider the following route, installed by Rails when you generate your
-  # application:
+  # Consider the following route, which you will find commented out at the
+  # bottom of your generated <tt>config/routes.rb</tt>:
   #
-  #   map.connect ':controller/:action/:id'
+  #   match ':controller(/:action(/:id(.:format)))'
   #
   # This route states that it expects requests to consist of a
-  # <tt>:controller</tt> followed by an <tt>:action</tt> that in turn is fed
-  # some <tt>:id</tt>.
+  # <tt>:controller</tt> followed optionally by an <tt>:action</tt> that in 
+  # turn is followed optionally by an <tt>:id</tt>, which in turn is followed
+  # optionally by a <tt>:format</tt>
   #
-  # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end up
-  # with:
+  # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end
+  # up with:
   #
   #   params = { :controller => 'blog',
   #              :action     => 'edit',
@@ -29,7 +30,7 @@ module ActionDispatch
   # Think of creating routes as drawing a map for your requests. The map tells
   # them where to go based on some predefined pattern:
   #
-  #   ActionController::Routing::Routes.draw do |map|
+  #   AppName::Applications.routes.draw do |map|
   #     Pattern 1 tells some request to go to one place
   #     Pattern 2 tell them to go to another
   #     ...
@@ -42,60 +43,16 @@ module ActionDispatch
   #
   # Other names simply map to a parameter as in the case of <tt>:id</tt>.
   #
-  # == Route priority
-  #
-  # Not all routes are created equally. Routes have priority defined by the
-  # order of appearance of the routes in the <tt>config/routes.rb</tt> file. The priority goes
-  # from top to bottom. The last route in that file is at the lowest priority
-  # and will be applied last. If no route matches, 404 is returned.
-  #
-  # Within blocks, the empty pattern is at the highest priority.
-  # In practice this works out nicely:
-  #
-  #   ActionController::Routing::Routes.draw do |map|
-  #     map.with_options :controller => 'blog' do |blog|
-  #       blog.show '',  :action => 'list'
-  #     end
-  #     map.connect ':controller/:action/:view'
-  #   end
-  #
-  # In this case, invoking blog controller (with an URL like '/blog/')
-  # without parameters will activate the 'list' action by default.
-  #
-  # == Defaults routes and default parameters
-  #
-  # Setting a default route is straightforward in Rails - you simply append a
-  # Hash at the end of your mapping to set any default parameters.
-  #
-  # Example:
-  #
-  #   ActionController::Routing:Routes.draw do |map|
-  #     map.connect ':controller/:action/:id', :controller => 'blog'
-  #   end
-  #
-  # This sets up +blog+ as the default controller if no other is specified.
-  # This means visiting '/' would invoke the blog controller.
-  #
-  # More formally, you can include arbitrary parameters in the route, thus:
-  #
-  #   map.connect ':controller/:action/:id', :action => 'show', :page => 'Dashboard'
-  #
-  # This will pass the :page parameter to all incoming requests that match this route.
-  #
-  # Note: The default routes, as provided by the Rails generator, make all actions in every
-  # controller accessible via GET requests. You should consider removing them or commenting
-  # them out if you're using named routes and resources.
-  #
   # == Named routes
   #
-  # Routes can be named with the syntax <tt>map.name_of_route options</tt>,
+  # Routes can be named by passing an <tt>:as</tt> option,
   # allowing for easy reference within your source as +name_of_route_url+
   # for the full URL and +name_of_route_path+ for the URI path.
   #
   # Example:
   #
   #   # In routes.rb
-  #   map.login 'login', :controller => 'accounts', :action => 'login'
+  #   match '/login' => 'accounts#login', :as => 'login'
   #
   #   # With render, redirect_to, tests, etc.
   #   redirect_to login_url
@@ -104,10 +61,10 @@ module ActionDispatch
   #
   #   redirect_to show_item_path(:id => 25)
   #
-  # Use <tt>map.root</tt> as a shorthand to name a route for the root path "".
+  # Use <tt>root</tt> as a shorthand to name a route for the root path "".
   #
   #   # In routes.rb
-  #   map.root :controller => 'blogs'
+  #   root :to => 'blogs#index'
   #
   #   # would recognize http://www.example.com/ as
   #   params = { :controller => 'blogs', :action => 'index' }
@@ -116,20 +73,14 @@ module ActionDispatch
   #   root_url   # => 'http://www.example.com/'
   #   root_path  # => ''
   #
-  # You can also specify an already-defined named route in your <tt>map.root</tt> call:
-  #
-  #   # In routes.rb
-  #   map.new_session :controller => 'sessions', :action => 'new'
-  #   map.root :new_session
-  #
-  # Note: when using +with_options+, the route is simply named after the
+  # Note: when using +controller+, the route is simply named after the
   # method you call on the block parameter rather than map.
   #
   #   # In routes.rb
-  #   map.with_options :controller => 'blog' do |blog|
-  #     blog.show    '',            :action  => 'list'
-  #     blog.delete  'delete/:id',  :action  => 'delete'
-  #     blog.edit    'edit/:id',    :action  => 'edit'
+  #   controller :blog do
+  #     match 'blog/show'     => :list
+  #     match 'blog/delete'   => :delete
+  #     match 'blog/edit/:id' => :edit
   #   end
   #
   #   # provides named routes for show, delete, and edit
@@ -139,12 +90,13 @@ module ActionDispatch
   #
   # Routes can generate pretty URLs. For example:
   #
-  #   map.connect 'articles/:year/:month/:day',
-  #               :controller => 'articles',
-  #               :action     => 'find_by_date',
-  #               :year       => /\d{4}/,
-  #               :month      => /\d{1,2}/,
-  #               :day        => /\d{1,2}/
+  #   match '/articles/:year/:month/:day', :constraints => {
+  #     :controller => 'articles',
+  #     :action     => 'find_by_date',
+  #     :year       => /\d{4}/,
+  #     :month      => /\d{1,2}/,
+  #     :day        => /\d{1,2}/
+  #   }
   #
   # Using the route above, the URL "http://localhost:3000/articles/2005/11/06"
   # maps to
@@ -154,42 +106,34 @@ module ActionDispatch
   # == Regular Expressions and parameters
   # You can specify a regular expression to define a format for a parameter.
   #
-  #   map.geocode 'geocode/:postalcode', :controller => 'geocode',
-  #               :action => 'show', :postalcode => /\d{5}(-\d{4})?/
-  #
-  # or, more formally:
+  #   controller 'geocode' do
+  #     match 'geocode/:postalcode' => :show', :constraints => {
+  #       :postalcode => /\d{5}(-\d{4})?/
+  #     }
   #
-  #   map.geocode 'geocode/:postalcode', :controller => 'geocode',
-  #               :action => 'show', :requirements => { :postalcode => /\d{5}(-\d{4})?/ }
-  #
-  # Formats can include the 'ignorecase' and 'extended syntax' regular
+  # Constraints can include the 'ignorecase' and 'extended syntax' regular
   # expression modifiers:
   #
-  #   map.geocode 'geocode/:postalcode', :controller => 'geocode',
-  #               :action => 'show', :postalcode => /hx\d\d\s\d[a-z]{2}/i
+  #   controller 'geocode' do
+  #     match 'geocode/:postalcode' => :show', :constraints => {
+  #       :postalcode => /hx\d\d\s\d[a-z]{2}/i
+  #     }
+  #   end
   #
-  #   map.geocode 'geocode/:postalcode', :controller => 'geocode',
-  #               :action => 'show',:requirements => {
-  #                 :postalcode => /# Postcode format
-  #                                 \d{5} #Prefix
-  #                                 (-\d{4})? #Suffix
-  #                                 /x
-  #               }
+  #   controller 'geocode' do
+  #     match 'geocode/:postalcode' => :show', :constraints => {
+  #       :postalcode => /# Postcode format
+  #          \d{5} #Prefix
+  #          (-\d{4})? #Suffix
+  #          /x
+  #     }
+  #   end
   #
   # Using the multiline match modifier will raise an ArgumentError.
   # Encoding regular expression modifiers are silently ignored. The
   # match will always use the default encoding or ASCII.
   #
-  # == Route globbing
-  #
-  # Specifying <tt>*[string]</tt> as part of a rule like:
-  #
-  #   map.connect '*path' , :controller => 'blog' , :action => 'unrecognized?'
-  #
-  # will glob all remaining parts of the route that were not recognized earlier.
-  # The globbed values are in <tt>params[:path]</tt> as an array of path segments.
-  #
-  # == Route conditions
+  # == HTTP Methods
   #
   # With conditions you can define restrictions on routes. Currently the only valid condition is <tt>:method</tt>.
   #
@@ -200,10 +144,8 @@ module ActionDispatch
   #
   # Example:
   #
-  #   map.connect 'post/:id', :controller => 'posts', :action => 'show',
-  #               :conditions => { :method => :get }
-  #   map.connect 'post/:id', :controller => 'posts', :action => 'create_comment',
-  #               :conditions => { :method => :post }
+  #   get  'post/:id' => 'posts#show'
+  #   post 'post/:id' => "posts#create_comment'
   #
   # Now, if you POST to <tt>/posts/:id</tt>, it will route to the <tt>create_comment</tt> action. A GET on the same
   # URL will route to the <tt>show</tt> action.
@@ -212,7 +154,7 @@ module ActionDispatch
   #
   # You can reload routes if you feel you must:
   #
-  #   ActionController::Routing::Routes.reload
+  #   Rails::Application.reload_routes!
   #
   # This will clear all named routes and reload routes.rb if the file has been modified from
   # last load. To absolutely force reloading, use <tt>reload!</tt>.