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

Conflicts:
	actionpack/lib/action_view/helpers/date_helper.rb
	railties/lib/rails/generators/rails/app/templates/config/initializers/wrap_parameters.rb.tt

actionpack/lib/abstract_controller/url_for.rb

@@ -1,3 +1,9 @@
+# Includes +url_for+ into the host class (e.g. an abstract controller or mailer). The class
+# has to provide a +RouteSet+ by implementing the <tt>_routes</tt> methods. Otherwise, an
+# exception will be raised.
+#
+# Note that this module is completely decoupled from HTTP - the only requirement is a valid 
+# <tt>_routes</tt> implementation.
 module AbstractController
   module UrlFor
     extend ActiveSupport::Concern

actionpack/lib/action_controller/metal/url_for.rb

@@ -1,3 +1,24 @@
+# Includes +url_for+ into the host class. The class has to provide a +RouteSet+ by implementing 
+# the <tt>_routes</tt> method. Otherwise, an exception will be raised.
+#
+# In addition to <tt>AbstractController::UrlFor</tt>, this module accesses the HTTP layer to define 
+# url options like the +host+. In order to do so, this module requires the host class
+# to implement +env+ and +request+, which need to be a Rack-compatible.
+#
+# Example:
+#
+#   class RootUrl
+#     include ActionController::UrlFor
+#     include Rails.application.routes.url_helpers
+#
+#     delegate :env, :request, :to => :controller
+#
+#     def initialize(controller)
+#       @controller = controller
+#       @url        = root_path # named route from the application.
+#     end
+#   end
+# => 
 module ActionController
   module UrlFor
     extend ActiveSupport::Concern

actionpack/lib/action_dispatch/http/url.rb

@@ -162,7 +162,7 @@ def subdomains(tld_length = @@tld_length)
 
       # Returns all the \subdomains as a string, so <tt>"dev.www"</tt> would be
       # returned for "dev.www.rubyonrails.org". You can specify a different <tt>tld_length</tt>,
-      # such as 2 to catch <tt>["www"]</tt> instead of <tt>"www.rubyonrails"</tt>
+      # such as 2 to catch <tt>"www"</tt> instead of <tt>"www.rubyonrails"</tt>
       # in "www.rubyonrails.co.uk".
       def subdomain(tld_length = @@tld_length)
         subdomains(tld_length).join(".")

actionpack/lib/action_dispatch/routing.rb

@@ -49,8 +49,8 @@ module ActionDispatch
   # You may wish to organize groups of controllers under a namespace. Most
   # commonly, you might group a number of administrative controllers under
   # an +admin+ namespace. You would place these controllers under the
-  # app/controllers/admin directory, and you can group them together in your
-  # router:
+  # <tt>app/controllers/admin</tt> directory, and you can group them together
+  # in your router:
   #
   #   namespace "admin" do
   #     resources :posts, :comments
@@ -152,7 +152,7 @@ module ActionDispatch
   #     }
   #   end
   #
-  # Using the multiline match modifier will raise an ArgumentError.
+  # 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.
   #

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -335,7 +335,7 @@ def root(options = {})
         #
         # [:on]
         #   Shorthand for wrapping routes in a specific RESTful context. Valid
-        #   values are :member, :collection, and :new.  Only use within
+        #   values are +:member+, +:collection+, and +:new+.  Only use within
         #   <tt>resource(s)</tt> block. For example:
         #
         #      resource :bar do
@@ -352,7 +352,7 @@ def root(options = {})
         #
         # [:constraints]
         #   Constrains parameters with a hash of regular expressions or an
-        #   object that responds to #matches?
+        #   object that responds to <tt>matches?</tt>
         #
         #     match 'path/:id', :constraints => { :id => /[A-Z]\d{5}/ }
         #
@@ -373,7 +373,7 @@ def root(options = {})
         #   See <tt>Scoping#defaults</tt> for its scope equivalent.
         #
         # [:anchor]
-        #   Boolean to anchor a #match pattern. Default is true. When set to
+        #   Boolean to anchor a <tt>match</tt> pattern. Default is true. When set to
         #   false, the pattern matches any request prefixed with the given path.
         #
         #     # Matches any request starting with 'path'
@@ -517,15 +517,15 @@ def map_method(method, *args, &block)
       # You may wish to organize groups of controllers under a namespace.
       # Most commonly, you might group a number of administrative controllers
       # under an +admin+ namespace. You would place these controllers under
-      # the app/controllers/admin directory, and you can group them together
-      # in your router:
+      # the <tt>app/controllers/admin</tt> directory, and you can group them
+      # together in your router:
       #
       #   namespace "admin" do
       #     resources :posts, :comments
       #   end
       #
       # This will create a number of routes for each of the posts and comments
-      # controller. For Admin::PostsController, Rails will create:
+      # controller. For <tt>Admin::PostsController</tt>, Rails will create:
       #
       #   GET	    /admin/posts
       #   GET	    /admin/posts/new
@@ -536,7 +536,7 @@ def map_method(method, *args, &block)
       #   DELETE  /admin/posts/1
       #
       # If you want to route /posts (without the prefix /admin) to
-      # Admin::PostsController, you could use
+      # <tt>Admin::PostsController</tt>, you could use
       #
       #   scope :module => "admin" do
       #     resources :posts
@@ -546,7 +546,7 @@ def map_method(method, *args, &block)
       #
       #   resources :posts, :module => "admin"
       #
-      # If you want to route /admin/posts to PostsController
+      # If you want to route /admin/posts to +PostsController+
       # (without the Admin:: module prefix), you could use
       #
       #   scope "/admin" do
@@ -555,11 +555,11 @@ def map_method(method, *args, &block)
       #
       # or, for a single case
       #
-      #   resources :posts, :path => "/admin"
+      #   resources :posts, :path => "/admin/posts"
       #
       # In each of these cases, the named routes remain the same as if you did
       # not use scope. In the last case, the following paths map to
-      # PostsController:
+      # +PostsController+:
       #
       #   GET	    /admin/posts
       #   GET	    /admin/posts/new
@@ -587,7 +587,7 @@ module Scoping
         #
         # === Examples
         #
-        #   # route /posts (without the prefix /admin) to Admin::PostsController
+        #   # route /posts (without the prefix /admin) to <tt>Admin::PostsController</tt>
         #   scope :module => "admin" do
         #     resources :posts
         #   end
@@ -597,7 +597,7 @@ module Scoping
         #     resources :posts
         #   end
         #
-        #   # prefix the routing helper name: sekret_posts_path instead of posts_path
+        #   # prefix the routing helper name: +sekret_posts_path+ instead of +posts_path+
         #   scope :as => "sekret" do
         #     resources :posts
         #   end
@@ -679,12 +679,12 @@ def controller(controller, options={})
         #     resources :posts
         #   end
         #
-        #   # maps to Sekret::PostsController rather than Admin::PostsController
+        #   # maps to <tt>Sekret::PostsController</tt> rather than <tt>Admin::PostsController</tt>
         #   namespace :admin, :module => "sekret" do
         #     resources :posts
         #   end
         #
-        #   # generates sekret_posts_path rather than admin_posts_path
+        #   # generates +sekret_posts_path+ rather than +admin_posts_path+
         #   namespace :admin, :as => "sekret" do
         #     resources :posts
         #   end
@@ -712,6 +712,7 @@ def namespace(path, options = {})
         #     constraints(:post_id => /\d+\.\d+) do
         #       resources :comments
         #     end
+        #   end
         #
         # === Restricting based on IP
         #
@@ -846,20 +847,20 @@ def override_keys(child) #:nodoc:
       # You may wish to organize groups of controllers under a namespace. Most
       # commonly, you might group a number of administrative controllers under
       # an +admin+ namespace. You would place these controllers under the
-      # app/controllers/admin directory, and you can group them together in your
-      # router:
+      # <tt>app/controllers/admin</tt> directory, and you can group them together
+      # in your router:
       #
       #   namespace "admin" do
       #     resources :posts, :comments
       #   end
       #
-      # By default the :id parameter doesn't accept dots. If you need to
-      # use dots as part of the :id parameter add a constraint which
+      # By default the +:id+ parameter doesn't accept dots. If you need to
+      # use dots as part of the +:id+ parameter add a constraint which
       # overrides this restriction, e.g:
       #
       #   resources :articles, :id => /[^\/]+/
       #
-      # This allows any character other than a slash as part of your :id.
+      # This allows any character other than a slash as part of your +:id+.
       #
       module Resources
         # CANONICAL_ACTIONS holds all actions that does not need a prefix or
@@ -975,7 +976,7 @@ def resources_path_names(options)
         #   resource :geocoder
         #
         # creates six different routes in your application, all mapping to
-        # the GeoCoders controller (note that the controller is named after
+        # the +GeoCoders+ controller (note that the controller is named after
         # the plural):
         #
         #   GET     /geocoder/new
@@ -1024,7 +1025,7 @@ def resource(*resources, &block)
         #   resources :photos
         #
         # creates seven different routes in your application, all mapping to
-        # the Photos controller:
+        # the +Photos+ controller:
         #
         #   GET     /photos/new
         #   POST    /photos
@@ -1107,11 +1108,11 @@ def resource(*resources, &block)
         #
         # === Examples
         #
-        #   # routes call Admin::PostsController
+        #   # routes call <tt>Admin::PostsController</tt>
         #   resources :posts, :module => "admin"
         #
         #   # resource actions are at /admin/posts.
-        #   resources :posts, :path => "admin"
+        #   resources :posts, :path => "admin/posts"
         def resources(*resources, &block)
           options = resources.extract_options!
 
@@ -1151,7 +1152,7 @@ def resources(*resources, &block)
         #   end
         #
         # This will enable Rails to recognize paths such as <tt>/photos/search</tt>
-        # with GET, and route to the search action of PhotosController. It will also
+        # with GET, and route to the search action of +PhotosController+. It will also
         # create the <tt>search_photos_url</tt> and <tt>search_photos_path</tt>
         # route helpers.
         def collection
@@ -1175,7 +1176,7 @@ def collection
         #   end
         #
         # This will recognize <tt>/photos/1/preview</tt> with GET, and route to the
-        # preview action of PhotosController. It will also create the
+        # preview action of +PhotosController+. It will also create the
         # <tt>preview_photo_url</tt> and <tt>preview_photo_path</tt> helpers.
         def member
           unless resource_scope?

actionpack/lib/action_dispatch/routing/url_for.rb

@@ -131,10 +131,10 @@ def url_options
       #
       # Examples:
       #
-      #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :port=>'8080'    # => 'http://somehost.org:8080/tasks/testing'
-      #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :anchor => 'ok', :only_path => true    # => '/tasks/testing#ok'
-      #    url_for :controller => 'tasks', :action => 'testing', :trailing_slash=>true  # => 'http://somehost.org/tasks/testing/'
-      #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :number => '33'  # => 'http://somehost.org/tasks/testing?number=33'
+      #    url_for :controller => 'tasks', :action => 'testing', :host => 'somehost.org', :port => '8080'    # => 'http://somehost.org:8080/tasks/testing'
+      #    url_for :controller => 'tasks', :action => 'testing', :host => 'somehost.org', :anchor => 'ok', :only_path => true    # => '/tasks/testing#ok'
+      #    url_for :controller => 'tasks', :action => 'testing', :trailing_slash => true  # => 'http://somehost.org/tasks/testing/'
+      #    url_for :controller => 'tasks', :action => 'testing', :host => 'somehost.org', :number => '33'  # => 'http://somehost.org/tasks/testing?number=33'
       def url_for(options = nil)
         case options
         when String

actionpack/lib/action_dispatch/testing/assertions/selector.rb

@@ -169,7 +169,7 @@ def css_select(*args)
       #   assert_select "title", "Welcome"
       #
       #   # Page title is "Welcome" and there is only one title element
-      #   assert_select "title", {:count=>1, :text=>"Welcome"},
+      #   assert_select "title", {:count => 1, :text => "Welcome"},
       #       "Wrong title or more than one title element"
       #
       #   # Page contains no forms

actionpack/lib/action_view/base.rb

@@ -85,11 +85,11 @@ module ActionView #:nodoc:
   #
   # Here are some basic examples:
   #
-  #   xml.em("emphasized")                              # => <em>emphasized</em>
-  #   xml.em { xml.b("emph & bold") }                   # => <em><b>emph &amp; bold</b></em>
-  #   xml.a("A Link", "href"=>"http://onestepback.org") # => <a href="http://onestepback.org">A Link</a>
-  #   xml.target("name"=>"compile", "option"=>"fast")   # => <target option="fast" name="compile"\>
-  #                                                     # NOTE: order of attributes is not specified.
+  #   xml.em("emphasized")                                 # => <em>emphasized</em>
+  #   xml.em { xml.b("emph & bold") }                      # => <em><b>emph &amp; bold</b></em>
+  #   xml.a("A Link", "href" => "http://onestepback.org")  # => <a href="http://onestepback.org">A Link</a>
+  #   xml.target("name" => "compile", "option" => "fast")  # => <target option="fast" name="compile"\>
+  #                                                        # NOTE: order of attributes is not specified.
   #
   # Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:
   #

actionpack/lib/action_view/helpers/atom_feed_helper.rb

@@ -81,8 +81,8 @@ module AtomFeedHelper
       #
       # The Atom spec defines five elements (content rights title subtitle
       # summary) which may directly contain xhtml content if :type => 'xhtml'
-      # is specified as an attribute.  If so, this helper will take care of
-      # the enclosing div and xhtml namespace declaration.  Example usage:
+      # is specified as an attribute. If so, this helper will take care of
+      # the enclosing div and xhtml namespace declaration. Example usage:
       #
       #    entry.summary :type => 'xhtml' do |xhtml|
       #      xhtml.p pluralize(order.line_items.count, "line item")
@@ -91,8 +91,8 @@ module AtomFeedHelper
       #    end
       #
       #
-      # atom_feed yields an AtomFeedBuilder instance.  Nested elements yield
-      # an AtomBuilder instance.
+      # <tt>atom_feed</tt> yields an +AtomFeedBuilder+ instance. Nested elements yield
+      # an +AtomBuilder+ instance.
       def atom_feed(options = {}, &block)
         if options[:schema_date]
           options[:schema_date] = options[:schema_date].strftime("%Y-%m-%d") if options[:schema_date].respond_to?(:strftime)

actionpack/lib/action_view/helpers/cache_helper.rb

@@ -3,7 +3,7 @@ module ActionView
   module Helpers
     module CacheHelper
       # This helper exposes a method for caching fragments of a view 
-      # rather than an entire action or page.  This technique is useful
+      # rather than an entire action or page. This technique is useful
       # caching pieces like menus, lists of newstopics, static HTML
       # fragments, and so on. This method takes a block that contains
       # the content you wish to cache.