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

16 files changed, 163 insertions, 128 deletions

diff --git a/actionpack/lib/abstract_controller/url_for.rb b/actionpack/lib/abstract_controller/url_for.rb
index e5d5bef6b4..e4261068d8 100644
--- a/actionpack/lib/abstract_controller/url_for.rb
+++ b/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
diff --git a/actionpack/lib/action_controller/metal/url_for.rb b/actionpack/lib/action_controller/metal/url_for.rb
index 6fc0cf1fb8..08132b1900 100644
--- a/actionpack/lib/action_controller/metal/url_for.rb
+++ b/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
diff --git a/actionpack/lib/action_dispatch/http/url.rb b/actionpack/lib/action_dispatch/http/url.rb
index d9c07d6ca3..8487b0fc8c 100644
--- a/actionpack/lib/action_dispatch/http/url.rb
+++ b/actionpack/lib/action_dispatch/http/url.rb
@@ -162,7 +162,7 @@ module ActionDispatch
 
       # 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(".")
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb
index 43fd93adf6..74c090f260 100644
--- a/actionpack/lib/action_dispatch/routing.rb
+++ b/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.
   #
diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index a65f6e1fce..3ba6094fbb 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -335,7 +335,7 @@ module ActionDispatch
         #
         # [: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 @@ module ActionDispatch
         #
         # [: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 @@ module ActionDispatch
         #   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 @@ 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:
+      # 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 @@ module ActionDispatch
       #   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 @@ module ActionDispatch
       #
       #   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 @@ module ActionDispatch
       #
       # 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 ActionDispatch
         #
         # === 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 ActionDispatch
         #     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 @@ module ActionDispatch
         #     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 @@ module ActionDispatch
         #     constraints(:post_id => /\d+\.\d+) do
         #       resources :comments
         #     end
+        #   end
         #
         # === Restricting based on IP
         #
@@ -846,20 +847,20 @@ 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
       #   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 @@ module ActionDispatch
         #   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 @@ module ActionDispatch
         #   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 @@ module ActionDispatch
         #
         # === 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 @@ module ActionDispatch
         #   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 @@ module ActionDispatch
         #   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?
diff --git a/actionpack/lib/action_dispatch/routing/url_for.rb b/actionpack/lib/action_dispatch/routing/url_for.rb
index d4db78a25a..5893f86798 100644
--- a/actionpack/lib/action_dispatch/routing/url_for.rb
+++ b/actionpack/lib/action_dispatch/routing/url_for.rb
@@ -131,10 +131,10 @@ module ActionDispatch
       #
       # 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
diff --git a/actionpack/lib/action_dispatch/testing/assertions/selector.rb b/actionpack/lib/action_dispatch/testing/assertions/selector.rb
index c67a0664dc..5fa91d1a76 100644
--- a/actionpack/lib/action_dispatch/testing/assertions/selector.rb
+++ b/actionpack/lib/action_dispatch/testing/assertions/selector.rb
@@ -169,7 +169,7 @@ module ActionDispatch
       #   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
diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb
index c98110353f..fd2970b8e2 100644
--- a/actionpack/lib/action_view/base.rb
+++ b/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:
   #
diff --git a/actionpack/lib/action_view/helpers/atom_feed_helper.rb b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
index 96e5722252..889ea8a763 100644
--- a/actionpack/lib/action_view/helpers/atom_feed_helper.rb
+++ b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
@@ -81,8 +81,8 @@ module ActionView
       #
       # 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 ActionView
       #    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)
diff --git a/actionpack/lib/action_view/helpers/cache_helper.rb b/actionpack/lib/action_view/helpers/cache_helper.rb
index 385378ea29..e81d03b537 100644
--- a/actionpack/lib/action_view/helpers/cache_helper.rb
+++ b/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. 
diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb
index d2ddaafcb3..853ab061d2 100644
--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/actionpack/lib/action_view/helpers/date_helper.rb
@@ -12,14 +12,14 @@ module ActionView
     # select-type methods share a number of common options that are as follows:
     #
     # * <tt>:prefix</tt> - overwrites the default prefix of "date" used for the select names. So specifying "birthday"
-    # would give birthday[month] instead of date[month] if passed to the select_month method.
+    # would give birthday[month] instead of date[month] if passed to the <tt>select_month</tt> method.
     # * <tt>:include_blank</tt> - set to true if it should be possible to set an empty date.
     # * <tt>:discard_type</tt> - set to true if you want to discard the type part of the select name. If set to true,
-    #   the select_month method would use simply "date" (which can be overwritten using <tt>:prefix</tt>) instead of
-    #   "date[month]".
+    #   the <tt>select_month</tt> method would use simply "date" (which can be overwritten using <tt>:prefix</tt>) instead
+    #   of "date[month]".
     module DateHelper
       # Reports the approximate distance in time between two Time or Date objects or integers as seconds.
-      # Set <tt>include_seconds</tt> to true if you want more detailed approximations when distance < 1 min, 29 secs
+      # Set <tt>include_seconds</tt> to true if you want more detailed approximations when distance < 1 min, 29 secs.
       # Distances are reported based on the following table:
       #
       #   0 <-> 29 secs                                                             # => less than a minute
@@ -119,7 +119,7 @@ module ActionView
         end
       end
 
-      # Like distance_of_time_in_words, but where <tt>to_time</tt> is fixed to <tt>Time.now</tt>.
+      # Like <tt>distance_of_time_in_words</tt>, but where <tt>to_time</tt> is fixed to <tt>Time.now</tt>.
       #
       # ==== Examples
       #   time_ago_in_words(3.minutes.from_now)       # => 3 minutes
@@ -176,7 +176,7 @@ module ActionView
       # NOTE: Discarded selects will default to 1. So if no month select is available, January will be assumed.
       #
       # ==== Examples
-      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
+      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute.
       #   date_select("post", "written_on")
       #
       #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute,
@@ -197,7 +197,7 @@ module ActionView
       #   # lacking a year field.
       #   date_select("user", "birthday", :order => [:month, :day])
       #
-      #   # Generates a date select that when POSTed is stored in the user variable, in the birthday attribute
+      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
       #   # which is initially set to the date 3 days from the current date
       #   date_select("post", "written_on", :default => 3.days.from_now)
       #
@@ -205,7 +205,7 @@ module ActionView
       #   # that will have a default day of 20.
       #   date_select("credit_card", "bill_due", :default => { :day => 20 })
       #
-      #   # Generates a date select with custom prompts
+      #   # Generates a date select with custom prompts.
       #   date_select("post", "written_on", :prompt => { :day => 'Select day', :month => 'Select month', :year => 'Select year' })
       #
       # The selects are prepared for multi-parameter assignment to an Active Record object.
@@ -222,22 +222,23 @@ module ActionView
       # with <tt>:ampm</tt> option.
       #
       # This method will also generate 3 input hidden tags, for the actual year, month and day unless the option
-      # <tt>:ignore_date</tt> is set to +true+.
+      # <tt>:ignore_date</tt> is set to +true+. If you set the <tt>:ignore_date</tt> to +true+, you must have a
+      # +date_select+ on the same method within the form otherwise an exception will be raised.
       #
       # If anything is passed in the html_options hash it will be applied to every select tag in the set.
       #
       # ==== Examples
-      #   # Creates a time select tag that, when POSTed, will be stored in the post variable in the sunrise attribute
+      #   # Creates a time select tag that, when POSTed, will be stored in the post variable in the sunrise attribute.
       #   time_select("post", "sunrise")
       #
       #   # Creates a time select tag with a seconds field that, when POSTed, will be stored in the post variables in
       #   # the sunrise attribute.
       #   time_select("post", "start_time", :include_seconds => true)
       #
-      #   # You can set the :minute_step to 15 which will give you: 00, 15, 30 and 45.
+      #   # You can set the <tt>:minute_step</tt> to 15 which will give you: 00, 15, 30 and 45.
       #   time_select 'game', 'game_time', {:minute_step => 15}
       #
-      #   # Creates a time select tag with a custom prompt. Use :prompt => true for generic prompts.
+      #   # Creates a time select tag with a custom prompt. Use <tt>:prompt => true</tt> for generic prompts.
       #   time_select("post", "written_on", :prompt => {:hour => 'Choose hour', :minute => 'Choose minute', :second => 'Choose seconds'})
       #   time_select("post", "written_on", :prompt => {:hour => true}) # generic prompt for hours
       #   time_select("post", "written_on", :prompt => true) # generic prompts for all
@@ -261,7 +262,7 @@ module ActionView
       #
       # ==== Examples
       #   # Generates a datetime select that, when POSTed, will be stored in the post variable in the written_on
-      #   # attribute
+      #   # attribute.
       #   datetime_select("post", "written_on")
       #
       #   # Generates a datetime select with a year select that starts at 1995 that, when POSTed, will be stored in the
@@ -279,7 +280,7 @@ module ActionView
       #   # as the written_on attribute.
       #   datetime_select("post", "written_on", :discard_type => true)
       #
-      #   # Generates a datetime select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   # Generates a datetime select with a custom prompt. Use <tt>:prompt => true</tt> for generic prompts.
       #   datetime_select("post", "written_on", :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
       #   datetime_select("post", "written_on", :prompt => {:hour => true}) # generic prompt for hours
       #   datetime_select("post", "written_on", :prompt => true) # generic prompts for all
@@ -301,7 +302,7 @@ module ActionView
       # ==== Examples
       #   my_date_time = Time.now + 4.days
       #
-      #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today)
+      #   # Generates a datetime select that defaults to the datetime in my_date_time (four days after today).
       #   select_datetime(my_date_time)
       #
       #   # Generates a datetime select that defaults to today (no specified datetime)
@@ -331,7 +332,7 @@ module ActionView
       #   # prefixed with 'payday' rather than 'date'
       #   select_datetime(my_date_time, :prefix => 'payday')
       #
-      #   # Generates a datetime select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   # Generates a datetime select with a custom prompt. Use <tt>:prompt => true</tt> for generic prompts.
       #   select_datetime(my_date_time, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
       #   select_datetime(my_date_time, :prompt => {:hour => true}) # generic prompt for hours
       #   select_datetime(my_date_time, :prompt => true) # generic prompts for all
@@ -350,10 +351,10 @@ module ActionView
       # ==== Examples
       #   my_date = Time.today + 6.days
       #
-      #   # Generates a date select that defaults to the date in my_date (six days after today)
+      #   # Generates a date select that defaults to the date in my_date (six days afteri today).
       #   select_date(my_date)
       #
-      #   # Generates a date select that defaults to today (no specified date)
+      #   # Generates a date select that defaults to today (no specified date).
       #   select_date()
       #
       #   # Generates a date select that defaults to the date in my_date (six days after today)
@@ -361,18 +362,18 @@ module ActionView
       #   select_date(my_date, :order => [:year, :month, :day])
       #
       #   # Generates a date select that discards the type of the field and defaults to the date in
-      #   # my_date (six days after today)
+      #   # my_date (six days after today).
       #   select_date(my_date, :discard_type => true)
       #
       #   # Generates a date select that defaults to the date in my_date,
-      #   # which has fields separated by '/'
+      #   # which has fields separated by '/'.
       #   select_date(my_date, :date_separator => '/')
       #
       #   # Generates a date select that defaults to the datetime in my_date (six days after today)
-      #   # prefixed with 'payday' rather than 'date'
+      #   # prefixed with 'payday' rather than 'date'.
       #   select_date(my_date, :prefix => 'payday')
       #
-      #   # Generates a date select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   # Generates a date select with a custom prompt. Use <tt>:prompt => true</tt> for generic prompts.
       #   select_date(my_date, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
       #   select_date(my_date, :prompt => {:hour => true}) # generic prompt for hours
       #   select_date(my_date, :prompt => true) # generic prompts for all
@@ -381,7 +382,7 @@ module ActionView
         DateTimeSelector.new(date, options, html_options).select_date
       end
 
-      # Returns a set of html select-tags (one for hour and minute)
+      # Returns a set of html select-tags (one for hour and minute).
       # You can set <tt>:time_separator</tt> key to format the output, and
       # the <tt>:include_seconds</tt> option to include an input for seconds.
       #
@@ -390,28 +391,28 @@ module ActionView
       # ==== Examples
       #   my_time = Time.now + 5.days + 7.hours + 3.minutes + 14.seconds
       #
-      #   # Generates a time select that defaults to the time in my_time
+      #   # Generates a time select that defaults to the time in my_time.
       #   select_time(my_time)
       #
-      #   # Generates a time select that defaults to the current time (no specified time)
+      #   # Generates a time select that defaults to the current time (no specified time).
       #   select_time()
       #
       #   # Generates a time select that defaults to the time in my_time,
-      #   # which has fields separated by ':'
+      #   # which has fields separated by ':'.
       #   select_time(my_time, :time_separator => ':')
       #
       #   # Generates a time select that defaults to the time in my_time,
-      #   # that also includes an input for seconds
+      #   # that also includes an input for seconds.
       #   select_time(my_time, :include_seconds => true)
       #
       #   # Generates a time select that defaults to the time in my_time, that has fields
-      #   # separated by ':' and includes an input for seconds
+      #   # separated by ':' and includes an input for seconds.
       #   select_time(my_time, :time_separator => ':', :include_seconds => true)
       #
       #   # Generate a time select field with hours in the AM/PM format
       #   select_time(my_time, :ampm => true)
       #
-      #   # Generates a time select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   # Generates a time select with a custom prompt. Use <tt>:prompt</tt> to true for generic prompts.
       #   select_time(my_time, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
       #   select_time(my_time, :prompt => {:hour => true}) # generic prompt for hours
       #   select_time(my_time, :prompt => true) # generic prompts for all
@@ -427,17 +428,17 @@ module ActionView
       # ==== Examples
       #   my_time = Time.now + 16.minutes
       #
-      #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
+      #   # Generates a select field for seconds that defaults to the seconds for the time in my_time.
       #   select_second(my_time)
       #
-      #   # Generates a select field for seconds that defaults to the number given
+      #   # Generates a select field for seconds that defaults to the number given.
       #   select_second(33)
       #
       #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
-      #   # that is named 'interval' rather than 'second'
+      #   # that is named 'interval' rather than 'second'.
       #   select_second(my_time, :field_name => 'interval')
       #
-      #   # Generates a select field for seconds with a custom prompt.  Use :prompt=>true for a
+      #   # Generates a select field for seconds with a custom prompt. Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_minute(14, :prompt => 'Choose seconds')
       #
@@ -453,17 +454,17 @@ module ActionView
       # ==== Examples
       #   my_time = Time.now + 6.hours
       #
-      #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
+      #   # Generates a select field for minutes that defaults to the minutes for the time in my_tiime.
       #   select_minute(my_time)
       #
-      #   # Generates a select field for minutes that defaults to the number given
+      #   # Generates a select field for minutes that defaults to the number given.
       #   select_minute(14)
       #
       #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
-      #   # that is named 'stride' rather than 'second'
+      #   # that is named 'stride' rather than 'second'.
       #   select_minute(my_time, :field_name => 'stride')
       #
-      #   # Generates a select field for minutes with a custom prompt.  Use :prompt=>true for a
+      #   # Generates a select field for minutes with a custom prompt. Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_minute(14, :prompt => 'Choose minutes')
       #
@@ -478,17 +479,17 @@ module ActionView
       # ==== Examples
       #   my_time = Time.now + 6.hours
       #
-      #   # Generates a select field for hours that defaults to the hour for the time in my_time
+      #   # Generates a select field for hours that defaults to the hour for the time in my_time.
       #   select_hour(my_time)
       #
-      #   # Generates a select field for hours that defaults to the number given
+      #   # Generates a select field for hours that defaults to the number given.
       #   select_hour(13)
       #
       #   # Generates a select field for hours that defaults to the minutes for the time in my_time
-      #   # that is named 'stride' rather than 'second'
+      #   # that is named 'stride' rather than 'second'.
       #   select_hour(my_time, :field_name => 'stride')
       #
-      #   # Generates a select field for hours with a custom prompt.  Use :prompt => true for a
+      #   # Generates a select field for hours with a custom prompt. Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_hour(13, :prompt => 'Choose hour')
       #
@@ -506,17 +507,17 @@ module ActionView
       # ==== Examples
       #   my_date = Time.today + 2.days
       #
-      #   # Generates a select field for days that defaults to the day for the date in my_date
+      #   # Generates a select field for days that defaults to the day for the date in my_date.
       #   select_day(my_time)
       #
-      #   # Generates a select field for days that defaults to the number given
+      #   # Generates a select field for days that defaults to the number given.
       #   select_day(5)
       #
       #   # Generates a select field for days that defaults to the day for the date in my_date
-      #   # that is named 'due' rather than 'day'
+      #   # that is named 'due' rather than 'day'.
       #   select_day(my_time, :field_name => 'due')
       #
-      #   # Generates a select field for days with a custom prompt.  Use :prompt => true for a
+      #   # Generates a select field for days with a custom prompt.  Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_day(5, :prompt => 'Choose day')
       #
@@ -539,7 +540,7 @@ module ActionView
       #   select_month(Date.today)
       #
       #   # Generates a select field for months that defaults to the current month that
-      #   # is named "start" rather than "month"
+      #   # is named "start" rather than "month".
       #   select_month(Date.today, :field_name => 'start')
       #
       #   # Generates a select field for months that defaults to the current month that
@@ -558,7 +559,7 @@ module ActionView
       #   # will use keys like "Januar", "Marts."
       #   select_month(Date.today, :use_month_names => %w(Januar Februar Marts ...))
       #
-      #   # Generates a select field for months with a custom prompt.  Use :prompt => true for a
+      #   # Generates a select field for months with a custom prompt. Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_month(14, :prompt => 'Choose month')
       #
@@ -574,22 +575,22 @@ module ActionView
       #
       # ==== Examples
       #   # Generates a select field for years that defaults to the current year that
-      #   # has ascending year values
+      #   # has ascending year values.
       #   select_year(Date.today, :start_year => 1992, :end_year => 2007)
       #
       #   # Generates a select field for years that defaults to the current year that
-      #   # is named 'birth' rather than 'year'
+      #   # is named 'birth' rather than 'year'.
       #   select_year(Date.today, :field_name => 'birth')
       #
       #   # Generates a select field for years that defaults to the current year that
-      #   # has descending year values
+      #   # has descending year values.
       #   select_year(Date.today, :start_year => 2005, :end_year => 1900)
       #
       #   # Generates a select field for years that defaults to the year 2006 that
-      #   # has ascending year values
+      #   # has ascending year values.
       #   select_year(2006, :start_year => 2000, :end_year => 2010)
       #
-      #   # Generates a select field for years with a custom prompt.  Use :prompt => true for a
+      #   # Generates a select field for years with a custom prompt. Use <tt>:prompt => true</tt> for a
       #   # generic prompt.
       #   select_year(14, :prompt => 'Choose year')
       #
@@ -783,7 +784,7 @@ module ActionView
         end
 
         # Returns translated month names, but also ensures that a custom month
-        # name array has a leading nil element
+        # name array has a leading nil element.
         def month_names
           month_names = @options[:use_month_names] || translated_month_names
           month_names.unshift(nil) if month_names.size < 13
@@ -791,13 +792,13 @@ module ActionView
         end
         memoize :month_names
 
-        # Returns translated month names
+        # Returns translated month names.
         #  => [nil, "January", "February", "March",
         #           "April", "May", "June", "July",
         #           "August", "September", "October",
         #           "November", "December"]
         #
-        # If :use_short_month option is set
+        # If <tt>:use_short_month</tt> option is set
         #  => [nil, "Jan", "Feb", "Mar", "Apr", "May", "Jun",
         #           "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
         def translated_month_names
@@ -805,13 +806,13 @@ module ActionView
           I18n.translate(key, :locale => @options[:locale])
         end
 
-        # Lookup month name for number
+        # Lookup month name for number.
         #  month_name(1) => "January"
         #
-        # If :use_month_numbers option is passed
+        # If <tt>:use_month_numbers</tt> option is passed
         #  month_name(1) => 1
         #
-        # If :add_month_numbers option is passed
+        # If <tt>:add_month_numbers</tt> option is passed
         #  month_name(1) => "1 - January"
         def month_name(number)
           if @options[:use_month_numbers]
@@ -832,16 +833,22 @@ module ActionView
           I18n.translate(:'date.order', :locale => @options[:locale]) || []
         end
 
-        # Build full select tag from date type and options
+        # Build full select tag from date type and options.
         def build_options_and_select(type, selected, options = {})
           build_select(type, build_options(selected, options))
         end
 
-        # Build select option html from date value and options
+        # Build select option html from date value and options.
         #  build_options(15, :start => 1, :end => 31)
         #  => "<option value="1">1</option>
         #      <option value=\"2\">2</option>
         #      <option value=\"3\">3</option>..."
+        #
+        # If <tt>:step</tt> options is passed
+        #  build_options(15, :start => 1, :end => 31, :step => 2)
+        #  => "<option value="1">1</option>
+        #      <option value=\"3\">3</option>
+        #      <option value=\"5\">5</option>..."
         def build_options(selected, options = {})
           start         = options.delete(:start) || 0
           stop          = options.delete(:end) || 59
@@ -860,7 +867,7 @@ module ActionView
           (select_options.join("\n") + "\n").html_safe
         end
 
-        # Builds select tag from date type and html select options
+        # Builds select tag from date type and html select options.
         #  build_select(:month, "<option value="1">January</option>...")
         #  => "<select id="post_written_on_2i" name="post[written_on(2i)]">
         #        <option value="1">January</option>...
@@ -880,7 +887,7 @@ module ActionView
           (content_tag(:select, select_html.html_safe, select_options) + "\n").html_safe
         end
 
-        # Builds a prompt option tag with supplied options or from default options
+        # Builds a prompt option tag with supplied options or from default options.
         #  prompt_option_tag(:month, :prompt => 'Select month')
         #  => "<option value="">Select month</option>"
         def prompt_option_tag(type, options)
@@ -897,7 +904,7 @@ module ActionView
           prompt ? content_tag(:option, prompt, :value => '') : ''
         end
 
-        # Builds hidden input tag for date part and value
+        # Builds hidden input tag for date part and value.
         #  build_hidden(:year, 2008)
         #  => "<input id="post_written_on_1i" name="post[written_on(1i)]" type="hidden" value="2008" />"
         def build_hidden(type, value)
@@ -909,7 +916,7 @@ module ActionView
           }.merge(@html_options.slice(:disabled))) + "\n").html_safe
         end
 
-        # Returns the name attribute for the input tag
+        # Returns the name attribute for the input tag.
         #  => post[written_on(1i)]
         def input_name_from_type(type)
           prefix = @options[:prefix] || ActionView::Helpers::DateTimeSelector::DEFAULT_PREFIX
@@ -923,7 +930,7 @@ module ActionView
           @options[:discard_type] ? prefix : "#{prefix}[#{field_name}]"
         end
 
-        # Returns the id attribute for the input tag
+        # Returns the id attribute for the input tag.
         #  => "post_written_on_1i"
         def input_id_from_type(type)
           input_name_from_type(type).gsub(/([\[\(])|(\]\[)/, '_').gsub(/[\]\)]/, '')
@@ -940,7 +947,7 @@ module ActionView
           select.html_safe
         end
 
-        # Returns the separator for a given datetime component
+        # Returns the separator for a given datetime component.
         def separator(type)
           case type
             when :year
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 7698602022..0aaa690129 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -274,10 +274,10 @@ module ActionView
       # You can optionally provide html attributes as the last element of the array.
       #
       # Examples:
-      #   options_for_select([ "Denmark", ["USA", {:class=>'bold'}], "Sweden" ], ["USA", "Sweden"])
+      #   options_for_select([ "Denmark", ["USA", {:class => 'bold'}], "Sweden" ], ["USA", "Sweden"])
       #     <option value="Denmark">Denmark</option>\n<option value="USA" class="bold" selected="selected">USA</option>\n<option value="Sweden" selected="selected">Sweden</option>
       #
-      #   options_for_select([["Dollar", "$", {:class=>"bold"}], ["Kroner", "DKK", {:onclick => "alert('HI');"}]])
+      #   options_for_select([["Dollar", "$", {:class => "bold"}], ["Kroner", "DKK", {:onclick => "alert('HI');"}]])
       #     <option value="$" class="bold">Dollar</option>\n<option value="DKK" onclick="alert('HI');">Kroner</option>
       #
       # If you wish to specify disabled option tags, set +selected+ to be a hash, with <tt>:disabled</tt> being either a value
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 9e0f8f32b7..65a98fb27a 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -82,22 +82,22 @@ module ActionView
       #   select_tag "people", options_from_collection_for_select(@people, "id", "name")
       #   # <select id="people" name="people"><option value="1">David</option></select>
       #
-      #   select_tag "people", "<option>David</option>"
+      #   select_tag "people", "<option>David</option>".html_safe
       #   # => <select id="people" name="people"><option>David</option></select>
       #
-      #   select_tag "count", "<option>1</option><option>2</option><option>3</option><option>4</option>"
+      #   select_tag "count", "<option>1</option><option>2</option><option>3</option><option>4</option>".html_safe
       #   # => <select id="count" name="count"><option>1</option><option>2</option>
       #   #    <option>3</option><option>4</option></select>
       #
-      #   select_tag "colors", "<option>Red</option><option>Green</option><option>Blue</option>", :multiple => true
+      #   select_tag "colors", "<option>Red</option><option>Green</option><option>Blue</option>".html_safe, :multiple => true
       #   # => <select id="colors" multiple="multiple" name="colors[]"><option>Red</option>
       #   #    <option>Green</option><option>Blue</option></select>
       #
-      #   select_tag "locations", "<option>Home</option><option selected="selected">Work</option><option>Out</option>"
+      #   select_tag "locations", "<option>Home</option><option selected="selected">Work</option><option>Out</option>".html_safe
       #   # => <select id="locations" name="locations"><option>Home</option><option selected='selected'>Work</option>
       #   #    <option>Out</option></select>
       #
-      #   select_tag "access", "<option>Read</option><option>Write</option>", :multiple => true, :class => 'form_input'
+      #   select_tag "access", "<option>Read</option><option>Write</option>".html_safe, :multiple => true, :class => 'form_input'
       #   # => <select class="form_input" id="access" multiple="multiple" name="access[]"><option>Read</option>
       #   #    <option>Write</option></select>
       #
@@ -107,7 +107,7 @@ module ActionView
       #   select_tag "people", options_from_collection_for_select(@people, "id", "name"), :prompt => "Select something"
       #   # => <select id="people" name="people"><option value="">Select something</option><option value="1">David</option></select>
       #
-      #   select_tag "destination", "<option>NYC</option><option>Paris</option><option>Rome</option>", :disabled => true
+      #   select_tag "destination", "<option>NYC</option><option>Paris</option><option>Rome</option>".html_safe, :disabled => true
       #   # => <select disabled="disabled" id="destination" name="destination"><option>NYC</option>
       #   #    <option>Paris</option><option>Rome</option></select>
       def select_tag(name, option_tags = nil, options = {})
diff --git a/actionpack/lib/action_view/helpers/translation_helper.rb b/actionpack/lib/action_view/helpers/translation_helper.rb
index ec9bdd5320..fd8fe417d0 100644
--- a/actionpack/lib/action_view/helpers/translation_helper.rb
+++ b/actionpack/lib/action_view/helpers/translation_helper.rb
@@ -15,10 +15,10 @@ module ActionView
   # = Action View Translation Helpers
   module Helpers
     module TranslationHelper
-      # Delegates to I18n#translate but also performs three additional functions.
+      # Delegates to <tt>I18n#translate</tt> but also performs three additional functions.
       #
-      # First, it'll pass the :rescue_format => :html option to I18n so that any
-      # thrown MissingTranslation messages will be turned into inline spans that
+      # First, it'll pass the <tt>:rescue_format => :html</tt> option to I18n so that any
+      # thrown +MissingTranslation+ messages will be turned into inline spans that
       #
       #   * have a "translation-missing" class set,
       #   * contain the missing key as a title attribute and
@@ -54,7 +54,7 @@ module ActionView
       end
       alias :t :translate
 
-      # Delegates to I18n.localize with no additional functionality.
+      # Delegates to <tt>I18n.localize</tt> with no additional functionality.
       def localize(*args)
         I18n.localize(*args)
       end
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index ffa9a5bb0b..5488c752cc 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -420,7 +420,7 @@ module ActionView
       end
 
       # Creates a link tag of the given +name+ using a URL created by the set of
-      # +options+ if +condition+ is true, in which case only the name is
+      # +options+ if +condition+ is true, otherwise only the name is
       # returned. To specialize the default behavior, you can pass a block that
       # accepts the name or the full argument list for +link_to_unless+ (see the examples
       # in +link_to_unless+).
diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb
index 98ecd15aa0..b99d24d281 100644
--- a/actionpack/lib/action_view/template.rb
+++ b/actionpack/lib/action_view/template.rb
@@ -79,9 +79,9 @@ module ActionView
     # you are handling out-of-band metadata, you are
     # also responsible for alerting the user to any
     # problems with converting the user's data to
-    # the default_internal.
+    # the <tt>default_internal</tt>.
     #
-    # To do so, simply raise the raise WrongEncodingError
+    # To do so, simply raise the raise +WrongEncodingError+
     # as follows:
     #
     #     raise WrongEncodingError.new(
@@ -198,7 +198,7 @@ module ActionView
       # Among other things, this method is responsible for properly setting
       # the encoding of the source. Until this point, we assume that the
       # source is BINARY data. If no additional information is supplied,
-      # we assume the encoding is the same as Encoding.default_external.
+      # we assume the encoding is the same as <tt>Encoding.default_external</tt>.
       #
       # The user can also specify the encoding via a comment on the first
       # line of the template (# encoding: NAME-OF-ENCODING). This will work
@@ -212,8 +212,8 @@ module ActionView
       # specifying the encoding. For instance, ERB supports <%# encoding: %>
       #
       # Otherwise, after we figure out the correct encoding, we then
-      # encode the source into Encoding.default_internal. In general,
-      # this means that templates will be UTF-8 inside of Rails,
+      # encode the source into <tt>Encoding.default_internal</tt>.
+      # In general, this means that templates will be UTF-8 inside of Rails,
       # regardless of the original source encoding.
       def compile(view, mod) #:nodoc:
         method_name = self.method_name