github/rails
1
1
Fork 0
mirror of https://github.com/github/rails.git synced 2026-04-26 03:00:59 -04:00
Code Issues Packages Projects Releases Wiki Activity

Make rdoc match current API

Browse Source 
Signed-off-by: Mikel Lindsaar <raasdnil@gmail.com>
This commit is contained in:
Sam Ruby
2010-01-29 15:23:59 -05:00
committed by Mikel Lindsaar
parent 5998dd7bb8
commit df8852d04d
1 changed files with 47 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
actionpack/lib/action_dispatch/routing.rb
View File

@@ -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})?/
# controller 'geocode' do
# match 'geocode/:postalcode' => :show', :constraints => {
# :postalcode => /\d{5}(-\d{4})?/
# }
#
# or, more formally:
#
# 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>.