Merge docrails.

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

10 files changed, 196 insertions, 183 deletions

diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index dfc7e2b3ed..e5a95a961c 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -11,8 +11,8 @@ module ActionView
     # === Using asset hosts
     # By default, Rails links to these assets on the current host in the public
     # folder, but you can direct Rails to link to assets from a dedicated assets server by 
-    # setting ActionController::Base.asset_host in your environment.rb.  For example,
-    # let's say your asset host is assets.example.com. 
+    # setting ActionController::Base.asset_host in your <tt>config/environment.rb</tt>.  For example,
+    # let's say your asset host is <tt>assets.example.com</tt>.
     #
     #   ActionController::Base.asset_host = "assets.example.com"
     #   image_tag("rails.png")
@@ -22,8 +22,8 @@ module ActionView
     #
     # This is useful since browsers typically open at most two connections to a single host,
     # which means your assets often wait in single file for their turn to load.  You can
-    # alleviate this by using a %d wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") 
-    # to automatically distribute asset requests among four hosts (e.g., assets0.example.com through assets3.example.com)
+    # alleviate this by using a <tt>%d</tt> wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com") 
+    # to automatically distribute asset requests among four hosts (e.g., "assets0.example.com" through "assets3.example.com")
     # so browsers will open eight connections rather than two.  
     #
     #   image_tag("rails.png")
@@ -293,9 +293,9 @@ module ActionView
       end
 
       # Computes the path to a stylesheet asset in the public stylesheets directory.
-      # If the +source+ filename has no extension, .css will be appended.
+      # If the +source+ filename has no extension, <tt>.css</tt> will be appended.
       # Full paths from the document root will be passed through.
-      # Used internally by stylesheet_link_tag to build the stylesheet path.
+      # Used internally by +stylesheet_link_tag+ to build the stylesheet path.
       #
       # ==== Examples
       #   stylesheet_path "style" # => /stylesheets/style.css
@@ -309,7 +309,7 @@ module ActionView
       alias_method :path_to_stylesheet, :stylesheet_path # aliased to avoid conflicts with a stylesheet_path named route
 
       # Returns a stylesheet link tag for the sources specified as arguments. If
-      # you don't specify an extension, .css will be appended automatically.
+      # you don't specify an extension, <tt>.css</tt> will be appended automatically.
       # You can modify the link attributes by passing a hash as the last argument.
       #
       # ==== Examples
@@ -379,7 +379,7 @@ module ActionView
 
       # Computes the path to an image asset in the public images directory.
       # Full paths from the document root will be passed through.
-      # Used internally by image_tag to build the image path.
+      # Used internally by +image_tag+ to build the image path.
       #
       # ==== Examples
       #   image_path("edit")                                         # => /images/edit
@@ -454,8 +454,8 @@ module ActionView
           end
         end
 
-        # Add the .ext if not present. Return full URLs otherwise untouched.
-        # Prefix with /dir/ if lacking a leading /. Account for relative URL
+        # Add the the extension +ext+ if not present. Return full URLs otherwise untouched.
+        # Prefix with <tt>/dir/</tt> if lacking a leading +/+. Account for relative URL
         # roots. Rewrite the asset path for cache-busting asset ids. Include
         # asset host, if configured, with the correct request protocol.
         def compute_public_path(source, dir, ext = nil, include_host = true)
@@ -502,9 +502,9 @@ module ActionView
             end
         end
 
-        # Pick an asset host for this source. Returns nil if no host is set,
+        # Pick an asset host for this source. Returns +nil+ if no host is set,
         # the host if no wildcard is set, the host interpolated with the
-        # numbers 0-3 if it contains %d (the number is the source hash mod 4),
+        # numbers 0-3 if it contains <tt>%d</tt> (the number is the source hash mod 4),
         # or the value returned from invoking the proc if it's a proc.
         def compute_asset_host(source)
           if host = ActionController::Base.asset_host
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 0962be2c79..0791feb9ac 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -86,15 +86,15 @@ module ActionView
       #     <%= f.text_field :author %><br />
       #   <% end %>
       #
-      # There, +form_for+ is able to generate the rest of RESTful parameters
+      # There, +form_for+ is able to generate the rest of RESTful form parameters
       # based on introspection on the record, but to understand what it does we
       # need to dig first into the alternative generic usage it is based upon.
       #
       # === Generic form_for
       #
-      # The generic way to call +form_for+ requires a few arguments:
+      # The generic way to call +form_for+ yields a form builder around a model:
       #
-      #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
+      #   <% form_for :person, :url => { :action => "update" } do |f| %>
       #     <%= f.error_messages %>
       #     First name: <%= f.text_field :first_name %><br />
       #     Last name : <%= f.text_field :last_name %><br />
@@ -102,21 +102,48 @@ module ActionView
       #     Admin?    : <%= f.check_box :admin %><br />
       #   <% end %>
       #
+      # There, the first argument is a symbol or string with the name of the
+      # object the form is about, and also the name of the instance variable the
+      # object is stored in.
+      #
+      # The form builder acts as a regular form helper that somehow carries the
+      # model. Thus, the idea is that
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name %>
+      #
+      # If the instance variable is not <tt>@person</tt> you can pass the actual
+      # record as the second argument:
+      #
+      #   <% form_for :person, person, :url => { :action => "update" } do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # In that case you can think
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name, :object => person %>
+      #
+      # You can even display error messages of the wrapped model this way:
+      #
+      #   <%= f.error_messages %>
+      #
+      # In any of its variants, the rightmost argument to +form_for+ is an
+      # optional hash of options:
+      #
+      # * <tt>:url</tt> - The URL the form is submitted to. It takes the same fields
+      #   you pass to +url_for+ or +link_to+. In particular you may pass here a
+      #   named route directly as well. Defaults to the current action.
+      # * <tt>:html</tt> - Optional HTML attributes for the form tag.
+      #
       # Worth noting is that the +form_for+ tag is called in a ERb evaluation block,
-      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. Also
-      # worth noting is that +form_for+ yields a form builder object, in this
-      # example as +f+, which emulates the API for the stand-alone FormHelper
-      # methods, but without the object name. So instead of <tt>text_field :person, :name</tt>,
-      # you get away with <tt>f.text_field :name</tt>. Notice that you can even do
-      # <tt><%= f.error_messages %></tt> to display the error messsages of the model
-      # object in question.
-      #
-      # Even further, the +form_for+ method allows you to more easily escape the
-      # instance variable convention. So while the stand-alone approach would require
-      # <tt>text_field :person, :name, :object => person</tt> to work with local
-      # variables instead of instance ones, the +form_for+ calls remain the same.
-      # You simply declare once with <tt>:person, person</tt> and all subsequent
-      # field calls save <tt>:person</tt> and <tt>:object => person</tt>.
+      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>.
       #
       # Also note that +form_for+ doesn't create an exclusive scope. It's still
       # possible to use both the stand-alone FormHelper methods and methods from
@@ -133,40 +160,32 @@ module ActionView
       # designed to work with an object as base, like FormOptionHelper#collection_select
       # and DateHelper#datetime_select.
       #
-      # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>.
-      # For example:
-      #
-      #   <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
-      #     ...
-      #   <% end %>
-      #
-      # The above form will then have the +id+ attribute with the value "person_form",
-      # which you can then style with CSS or manipulate with JavaScript.
-      #
-      # === Relying on record identification
+      # === Resource-oriented style
       #
       # As we said above, in addition to manually configuring the +form_for+ call,
-      # you can rely on record identification, which will use the conventions and
-      # named routes of that approach. This is the preferred way to use +form_for+
-      # nowadays:
+      # you can rely on automated resource identification, which will use the conventions
+      # and named routes of that approach. This is the preferred way to use +form_for+
+      # nowadays.
+      #
+      # For example, if <tt>@post</tt> is an existing record you want to edit
       #
-      #   <% form_for(@post) do |f| %>
+      #   <% form_for @post do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # is equivalent to something like:
       #
       #   <% form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
       #     ...
       #   <% end %>
       #
-      # And for new records:
+      # And for new records
       #
       #   <% form_for(Post.new) do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # expands to
       #
       #   <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
       #     ...
@@ -305,13 +324,13 @@ module ActionView
       #
       # ==== Examples
       #   label(:post, :title)
-      #   #=> <label for="post_title">Title</label>
+      #   # => <label for="post_title">Title</label>
       #
       #   label(:post, :title, "A short title")
-      #   #=> <label for="post_title">A short title</label>
+      #   # => <label for="post_title">A short title</label>
       #
       #   label(:post, :title, "A short title", :class => "title_label")
-      #   #=> <label for="post_title" class="title_label">A short title</label>
+      #   # => <label for="post_title" class="title_label">A short title</label>
       #
       def label(object_name, method, text = nil, options = {})
         InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_label_tag(text, options)
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 6f3818659e..e0a097e367 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -119,7 +119,7 @@ module ActionView
       #     end
       #   end
       #
-      # Sample usage (selecting the associated +Author+ for an instance of +Post+, <tt>@post</tt>):
+      # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
       #   collection_select(:post, :author_id, Author.find(:all), :id, :name_with_initial, {:prompt => true})
       #
       # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
@@ -144,7 +144,7 @@ module ActionView
       # In addition to the <tt>:include_blank</tt> option documented above,
       # this method also supports a <tt>:model</tt> option, which defaults
       # to TimeZone. This may be used by users to specify a different time
-      # zone model object. (See #time_zone_options_for_select for more
+      # zone model object. (See +time_zone_options_for_select+ for more
       # information.)
       #
       # You can also supply an array of TimeZone objects
@@ -153,7 +153,7 @@ module ActionView
       # obtaining a list of the US time zones.)
       #
       # Finally, this method supports a <tt>:default</tt> option, which selects
-      # a default TimeZone if the object's time zone is nil.
+      # a default TimeZone if the object's time zone is +nil+.
       #
       # Examples:
       #   time_zone_select( "user", "time_zone", nil, :include_blank => true)
@@ -172,7 +172,7 @@ module ActionView
       # Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container
       # where the elements respond to first and last (such as a two-element array), the "lasts" serve as option values and
       # the "firsts" as option text. Hashes are turned into this form automatically, so the keys become "firsts" and values
-      # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +Selected+
+      # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag.  +selected+
       # may also be an array of values to be selected when using a multiple select.
       #
       # Examples (call, result):
@@ -217,24 +217,22 @@ module ActionView
         options_for_select(options, selected)
       end
 
-      # Returns a string of <tt><option></tt> tags, like <tt>#options_from_collection_for_select</tt>, but
+      # Returns a string of <tt><option></tt> tags, like <tt>options_from_collection_for_select</tt>, but
       # groups them by <tt><optgroup></tt> tags based on the object relationships of the arguments.
       #
       # Parameters:
-      # +collection+::          An array of objects representing the <tt><optgroup></tt> tags
-      # +group_method+::        The name of a method which, when called on a member of +collection+, returns an
-      #                         array of child objects representing the <tt><option></tt> tags
-      # +group_label_method+::  The name of a method which, when called on a member of +collection+, returns a
-      #                         string to be used as the +label+ attribute for its <tt><optgroup></tt> tag
-      # +option_key_method+::   The name of a method which, when called on a child object of a member of
-      #                         +collection+, returns a value to be used as the +value+ attribute for its
-      #                         <tt><option></tt> tag
-      # +option_value_method+:: The name of a method which, when called on a child object of a member of
-      #                         +collection+, returns a value to be used as the contents of its
-      #                         <tt><option></tt> tag
-      # +selected_key+::        A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
-      #                         which will have the +selected+ attribute set. Corresponds to the return value
-      #                         of one of the calls to +option_key_method+. If +nil+, no selection is made.
+      # * +collection+ - An array of objects representing the <tt><optgroup></tt> tags.
+      # * +group_method+ - The name of a method which, when called on a member of +collection+, returns an
+      #   array of child objects representing the <tt><option></tt> tags.
+      # * group_label_method+ - The name of a method which, when called on a member of +collection+, returns a
+      #   string to be used as the +label+ attribute for its <tt><optgroup></tt> tag.
+      # * +option_key_method+ - The name of a method which, when called on a child object of a member of
+      #   +collection+, returns a value to be used as the +value+ attribute for its <tt><option></tt> tag.
+      # * +option_value_method+ - The name of a method which, when called on a child object of a member of
+      #   +collection+, returns a value to be used as the contents of its <tt><option></tt> tag.
+      # * +selected_key+ - A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
+      #   which will have the +selected+ attribute set. Corresponds to the return value of one of the calls
+      #   to +option_key_method+. If +nil+, no selection is made.
       #
       # Example object structure for use with this method:
       #   class Continent < ActiveRecord::Base
@@ -300,8 +298,8 @@ module ActionView
       # a TimeZone.
       #
       # By default, +model+ is the TimeZone constant (which can be obtained
-      # in ActiveRecord as a value object). The only requirement is that the
-      # +model+ parameter be an object that responds to #all, and returns
+      # in Active Record as a value object). The only requirement is that the
+      # +model+ parameter be an object that responds to +all+, and returns
       # an array of objects that represent time zones.
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 922a0662fe..ca58f4ba26 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -3,7 +3,7 @@ require 'action_view/helpers/tag_helper'
 
 module ActionView
   module Helpers
-    # Provides a number of methods for creating form tags that doesn't rely on an ActiveRecord object assigned to the template like
+    # Provides a number of methods for creating form tags that doesn't rely on an Active Record object assigned to the template like
     # FormHelper does. Instead, you provide the names and values manually.
     #
     # NOTE: The HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying 
@@ -14,9 +14,9 @@ module ActionView
       #
       # ==== Options
       # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data".
-      # * <tt>:method</tt>    - The method to use when submitting the form, usually either "get" or "post".
-      #                         If "put", "delete", or another verb is used, a hidden input with name _method 
-      #                         is added to simulate the verb over post.
+      # * <tt>:method</tt> - The method to use when submitting the form, usually either "get" or "post".
+      #   If "put", "delete", or another verb is used, a hidden input with name <tt>_method</tt>
+      #   is added to simulate the verb over post.
       # * A list of parameters to feed to the URL the form will be posted to.
       #
       # ==== Examples
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index 04bf5f2a30..602832e470 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -595,8 +595,8 @@ module ActionView
         # JavaScript sent with a Content-type of "text/javascript".
         #
         # Create new instances with PrototypeHelper#update_page or with 
-        # ActionController::Base#render, then call #insert_html, #replace_html, 
-        # #remove, #show, #hide, #visual_effect, or any other of the built-in 
+        # ActionController::Base#render, then call +insert_html+, +replace_html+, 
+        # +remove+, +show+, +hide+, +visual_effect+, or any other of the built-in 
         # methods on the yielded generator in any order you like to modify the 
         # content and appearance of the current page. 
         #
@@ -687,7 +687,7 @@ module ActionView
             end
           end
           
-          # Returns an object whose <tt>#to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript 
+          # Returns an object whose <tt>to_json</tt> evaluates to +code+. Use this to pass a literal JavaScript 
           # expression as an argument to another JavaScriptGenerator method.
           def literal(code)
             ActiveSupport::JSON::Variable.new(code.to_s)
@@ -1173,7 +1173,7 @@ module ActionView
         super(generator)
       end
 
-      # The JSON Encoder calls this to check for the #to_json method
+      # The JSON Encoder calls this to check for the +to_json+ method
       # Since it's a blank slate object, I suppose it responds to anything.
       def respond_to?(method)
         true
diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb
index 40b66be79f..66c596f3a9 100644
--- a/actionpack/lib/action_view/helpers/record_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb
@@ -2,7 +2,7 @@ module ActionView
   module Helpers
     module RecordTagHelper
       # Produces a wrapper DIV element with id and class parameters that
-      # relate to the specified ActiveRecord object. Usage example:
+      # relate to the specified Active Record object. Usage example:
       #
       #    <% div_for(@person, :class => "foo") do %>
       #       <%=h @person.name %>
@@ -17,7 +17,7 @@ module ActionView
       end
   
       # content_tag_for creates an HTML element with id and class parameters
-      # that relate to the specified ActiveRecord object. For example:
+      # that relate to the specified Active Record object. For example:
       #
       #    <% content_tag_for(:tr, @person) do %>
       #      <td><%=h @person.first_name %></td>
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index 6c0a7ec25c..b0dacfe964 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -57,7 +57,7 @@ module ActionView
         self.class.white_list_sanitizer.sanitize(html, options)
       end
 
-      # Sanitizes a block of css code.  Used by #sanitize when it comes across a style attribute
+      # Sanitizes a block of CSS code. Used by +sanitize+ when it comes across a style attribute.
       def sanitize_css(style)
         self.class.white_list_sanitizer.sanitize_css(style)
       end
@@ -111,8 +111,8 @@ module ActionView
           end
         end
         
-        # Gets the HTML::FullSanitizer instance used by strip_tags.  Replace with
-        # any object that responds to #sanitize
+        # Gets the HTML::FullSanitizer instance used by +strip_tags+.  Replace with
+        # any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.full_sanitizer = MySpecialSanitizer.new
@@ -122,8 +122,8 @@ module ActionView
           @full_sanitizer ||= HTML::FullSanitizer.new
         end
 
-        # Gets the HTML::LinkSanitizer instance used by strip_links.  Replace with
-        # any object that responds to #sanitize
+        # Gets the HTML::LinkSanitizer instance used by +strip_links+.  Replace with
+        # any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.link_sanitizer = MySpecialSanitizer.new
@@ -133,8 +133,8 @@ module ActionView
           @link_sanitizer ||= HTML::LinkSanitizer.new
         end
 
-        # Gets the HTML::WhiteListSanitizer instance used by sanitize and sanitize_css.
-        # Replace with any object that responds to #sanitize
+        # Gets the HTML::WhiteListSanitizer instance used by sanitize and +sanitize_css+.
+        # Replace with any object that responds to +sanitize+.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.white_list_sanitizer = MySpecialSanitizer.new
@@ -144,7 +144,7 @@ module ActionView
           @white_list_sanitizer ||= HTML::WhiteListSanitizer.new
         end
 
-        # Adds valid HTML attributes that the #sanitize helper checks for URIs.
+        # Adds valid HTML attributes that the +sanitize+ helper checks for URIs.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_uri_attributes = 'lowsrc', 'target'
@@ -154,7 +154,7 @@ module ActionView
           HTML::WhiteListSanitizer.uri_attributes.merge(attributes)
         end
 
-        # Adds to the Set of 'bad' tags for the #sanitize helper.
+        # Adds to the Set of 'bad' tags for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_bad_tags = 'embed', 'object'
@@ -163,7 +163,8 @@ module ActionView
         def sanitized_bad_tags=(attributes)
           HTML::WhiteListSanitizer.bad_tags.merge(attributes)
         end
-        # Adds to the Set of allowed tags for the #sanitize helper.
+
+        # Adds to the Set of allowed tags for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
@@ -173,7 +174,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_tags.merge(attributes)
         end
 
-        # Adds to the Set of allowed html attributes for the #sanitize helper.
+        # Adds to the Set of allowed HTML attributes for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_attributes = 'onclick', 'longdesc'
@@ -183,7 +184,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_attributes.merge(attributes)
         end
 
-        # Adds to the Set of allowed css properties for the #sanitize and #sanitize_css heleprs.
+        # Adds to the Set of allowed CSS properties for the #sanitize and +sanitize_css+ heleprs.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_css_properties = 'expression'
@@ -193,7 +194,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_css_properties.merge(attributes)
         end
 
-        # Adds to the Set of allowed css keywords for the #sanitize and #sanitize_css helpers.
+        # Adds to the Set of allowed CSS keywords for the +sanitize+ and +sanitize_css+ helpers.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_css_keywords = 'expression'
@@ -203,7 +204,7 @@ module ActionView
           HTML::WhiteListSanitizer.allowed_css_keywords.merge(attributes)
         end
 
-        # Adds to the Set of allowed shorthand css properties for the #sanitize and #sanitize_css helpers.
+        # Adds to the Set of allowed shorthand CSS properties for the +sanitize+ and +sanitize_css+ helpers.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_shorthand_css_properties = 'expression'
@@ -213,7 +214,7 @@ module ActionView
           HTML::WhiteListSanitizer.shorthand_css_properties.merge(attributes)
         end
 
-        # Adds to the Set of allowed protocols for the #sanitize helper.
+        # Adds to the Set of allowed protocols for the +sanitize+ helper.
         #
         #   Rails::Initializer.run do |config|
         #     config.action_view.sanitized_allowed_protocols = 'ssh', 'feed'
diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
index 12b4cfd3f8..c9b2761cb8 100644
--- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
+++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
@@ -26,9 +26,9 @@ module ActionView
       #         :url => { :action => "reload" }, 
       #         :complete => visual_effect(:highlight, "posts", :duration => 0.5)
       #
-      # If no element_id is given, it assumes "element" which should be a local
+      # If no +element_id+ is given, it assumes "element" which should be a local
       # variable in the generated JavaScript execution context. This can be 
-      # used for example with drop_receiving_element:
+      # used for example with +drop_receiving_element+:
       #
       #   <%= drop_receiving_element (...), :loading => visual_effect(:fade) %>
       #
@@ -67,6 +67,7 @@ module ActionView
       # element as parameters.
       #
       # Example:
+      #
       #   <%= sortable_element("my_list", :url => { :action => "order" }) %>
       #
       # In the example, the action gets a "my_list" array parameter 
@@ -79,60 +80,56 @@ module ActionView
       # 
       # Additional +options+ are:
       #
-      # <tt>:format</tt>::               A regular expression to determine what to send
-      #                                  as the serialized id to the server (the default
-      #                                  is <tt>/^[^_]*_(.*)$/</tt>).
-      #                                  
-      # <tt>:constraint</tt>::           Whether to constrain the dragging to either <tt>:horizontal</tt>
-      #                                  or <tt>:vertical</tt> (or false to make it unconstrained).
-      #                                   
-      # <tt>:overlap</tt>::              Calculate the item overlap in the <tt>:horizontal</tt> or 
-      #                                  <tt>:vertical</tt> direction.
-      #                                   
-      # <tt>:tag</tt>::                  Which children of the container element to treat as
-      #                                  sortable (default is <tt>li</tt>).
-      #                                  
-      # <tt>:containment</tt>::          Takes an element or array of elements to treat as
-      #                                  potential drop targets (defaults to the original
-      #                                  target element).
-      #                                  
-      # <tt>:only</tt>::                 A CSS class name or arry of class names used to filter
-      #                                  out child elements as candidates.
-      #                                  
-      # <tt>:scroll</tt>::               Determines whether to scroll the list during drag
-      #                                  operations if the list runs past the visual border.
-      #                                  
-      # <tt>:tree</tt>::                 Determines whether to treat nested lists as part of the
-      #                                  main sortable list. This means that you can create multi-
-      #                                  layer lists, and not only sort items at the same level,
-      #                                  but drag and sort items between levels.
-      #                                  
-      # <tt>:hoverclass</tt>::           If set, the Droppable will have this additional CSS class
-      #                                  when an accepted Draggable is hovered over it.                         
-      #                                 
-      # <tt>:handle</tt>::               Sets whether the element should only be draggable by an
-      #                                  embedded handle. The value may be a string referencing a
-      #                                  CSS class value (as of script.aculo.us V1.5). The first
-      #                                  child/grandchild/etc. element found within the element
-      #                                  that has this CSS class value will be used as the handle.
-      #
-      # <tt>:ghosting</tt>::             Clones the element and drags the clone, leaving the original
-      #                                  in place until the clone is dropped (default is <tt>false</tt>).
-      #       
-      # <tt>:dropOnEmpty</tt>::          If set to true, the Sortable container will be made into
-      #                                  a Droppable, that can receive a Draggable (as according to
-      #                                  the containment rules) as a child element when there are no
-      #                                  more elements inside (default is <tt>false</tt>).
-      #       
-      # <tt>:onChange</tt>::             Called whenever the sort order changes while dragging. When
-      #                                  dragging from one Sortable to another, the callback is
-      #                                  called once on each Sortable. Gets the affected element as
-      #                                  its parameter.
-      #                                 
-      # <tt>:onUpdate</tt>::             Called when the drag ends and the Sortable's order is
-      #                                  changed in any way. When dragging from one Sortable to
-      #                                  another, the callback is called once on each Sortable. Gets
-      #                                  the container as its parameter.
+      # * <tt>:format</tt> - A regular expression to determine what to send as the
+      #   serialized id to the server (the default is <tt>/^[^_]*_(.*)$/</tt>).
+      #                           
+      # * <tt>:constraint</tt> - Whether to constrain the dragging to either
+      #   <tt>:horizontal</tt> or <tt>:vertical</tt> (or false to make it unconstrained).
+      #                            
+      # * <tt>:overlap</tt> - Calculate the item overlap in the <tt>:horizontal</tt>
+      #   or <tt>:vertical</tt> direction.
+      #                            
+      # * <tt>:tag</tt> - Which children of the container element to treat as
+      #   sortable (default is <tt>li</tt>).
+      #                          
+      # * <tt>:containment</tt> - Takes an element or array of elements to treat as
+      #   potential drop targets (defaults to the original target element).
+      #                          
+      # * <tt>:only</tt> - A CSS class name or arry of class names used to filter
+      #   out child elements as candidates.
+      #                          
+      # * <tt>:scroll</tt> - Determines whether to scroll the list during drag
+      #   operations if the list runs past the visual border.
+      #                          
+      # * <tt>:tree</tt> - Determines whether to treat nested lists as part of the
+      #   main sortable list. This means that you can create multi-layer lists,
+      #   and not only sort items at the same level, but drag and sort items
+      #   between levels.
+      #                          
+      # * <tt>:hoverclass</tt> - If set, the Droppable will have this additional CSS class
+      #   when an accepted Draggable is hovered over it.                         
+      #                          
+      # * <tt>:handle</tt> - Sets whether the element should only be draggable by an
+      #   embedded handle. The value may be a string referencing a CSS class value
+      #   (as of script.aculo.us V1.5). The first child/grandchild/etc. element
+      #   found within the element that has this CSS class value will be used as
+      #   the handle.
+      #                          
+      # * <tt>:ghosting</tt> - Clones the element and drags the clone, leaving
+      #   the original in place until the clone is dropped (default is <tt>false</tt>).
+      #                          
+      # * <tt>:dropOnEmpty</tt> - If true the Sortable container will be made into
+      #   a Droppable, that can receive a Draggable (as according to the containment
+      #   rules) as a child element when there are no more elements inside (default
+      #   is <tt>false</tt>).
+      #                          
+      # * <tt>:onChange</tt> - Called whenever the sort order changes while dragging. When
+      #   dragging from one Sortable to another, the callback is called once on each
+      #   Sortable. Gets the affected element as its parameter.
+      #                          
+      # * <tt>:onUpdate</tt> - Called when the drag ends and the Sortable's order is
+      #   changed in any way. When dragging from one Sortable to another, the callback
+      #   is called once on each Sortable. Gets the container as its parameter.
       #                                                                                         
       # See http://script.aculo.us for more documentation.
       def sortable_element(element_id, options = {})
@@ -170,8 +167,8 @@ module ActionView
       end
 
       # Makes the element with the DOM ID specified by +element_id+ receive
-      # dropped draggable elements (created by draggable_element).
-      # and make an AJAX call  By default, the action called gets the DOM ID 
+      # dropped draggable elements (created by +draggable_element+).
+      # and make an AJAX call. By default, the action called gets the DOM ID 
       # of the element as parameter.
       #
       # Example:
@@ -182,32 +179,30 @@ module ActionView
       # http://script.aculo.us for more documentation.
       #
       # Some of these +options+ include:
-      # <tt>:accept</tt>::               Set this to a string or an array of strings describing the
-      #                                  allowable CSS classes that the draggable_element must have in order 
-      #                                  to be accepted by this drop_receiving_element.
-      #
-      # <tt>:confirm</tt>::              Adds a confirmation dialog.
-      #                                 
-      #                                  Example:
-      #                                    :confirm => "Are you sure you want to do this?"
-      #                                 
-      # <tt>:hoverclass</tt>::           If set, the drop_receiving_element will have this additional CSS class
-      #                                  when an accepted draggable_element is hovered over it.                         
-      #                                  
-      # <tt>:onDrop</tt>::               Called when a draggable_element is dropped onto this element.  
-      #                                  Override this callback with a javascript expression to 
-      #                                  change the default drop behavour.
-      #                                 
-      #                                  Example:
-      #                                    :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
-      #                          
-      #                                  This callback gets three parameters:      
-      #                                  The +Draggable+ element, the +Droppable+ element and the 
-      #                                  +Event+ object.  You can extract additional information about the 
-      #                                  drop - like if the Ctrl or Shift keys were pressed - from the +Event+ object.
-      #
-      # <tt>:with</tt>::                 A JavaScript expression specifying the parameters for the XMLHttpRequest.
-      #                                  Any expressions should return a valid URL query string.
+      # * <tt>:accept</tt> - Set this to a string or an array of strings describing the
+      #   allowable CSS classes that the +draggable_element+ must have in order 
+      #   to be accepted by this +drop_receiving_element+.
+      #                          
+      # * <tt>:confirm</tt> - Adds a confirmation dialog. Example:
+      #                     
+      #     :confirm => "Are you sure you want to do this?"
+      #                          
+      # * <tt>:hoverclass</tt> - If set, the +drop_receiving_element+ will have
+      #   this additional CSS class when an accepted +draggable_element+ is
+      #   hovered over it.                         
+      #                          
+      # * <tt>:onDrop</tt> - Called when a +draggable_element+ is dropped onto
+      #   this element. Override this callback with a JavaScript expression to 
+      #   change the default drop behavour. Example:
+      #                          
+      #     :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
+      #                          
+      #   This callback gets three parameters: The Draggable element, the Droppable
+      #   element and the Event object. You can extract additional information about
+      #   the drop - like if the Ctrl or Shift keys were pressed - from the Event object.
+      #                          
+      # * <tt>:with</tt> - A JavaScript expression specifying the parameters for
+      #   the XMLHttpRequest. Any expressions should return a valid URL query string.
       def drop_receiving_element(element_id, options = {})
         javascript_tag(drop_receiving_element_js(element_id, options).chop!)
       end
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 38c8d18cb0..4b12adf225 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -10,7 +10,7 @@ module ActionView
       include JavaScriptHelper
 
       # Returns the URL for the set of +options+ provided. This takes the
-      # same options as url_for in ActionController (see the
+      # same options as +url_for+ in Action Controller (see the
       # documentation for ActionController::Base#url_for). Note that by default
       # <tt>:only_path</tt> is <tt>true</tt> so you'll get the relative /controller/action
       # instead of the fully qualified URL like http://example.com/controller/action.
diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb
index 2cda3d94b5..369526188f 100644
--- a/actionpack/lib/action_view/template.rb
+++ b/actionpack/lib/action_view/template.rb
@@ -93,9 +93,9 @@ module ActionView #:nodoc:
     # Register a class that knows how to handle template files with the given
     # extension. This can be used to implement new template types.
     # The constructor for the class must take the ActiveView::Base instance
-    # as a parameter, and the class must implement a #render method that
+    # as a parameter, and the class must implement a +render+ method that
     # takes the contents of the template to render as well as the Hash of
-    # local assigns available to the template. The #render method ought to
+    # local assigns available to the template. The +render+ method ought to
     # return the rendered template as a string.
     def self.register_template_handler(extension, klass)
       @@template_handlers[extension.to_sym] = klass