Improve documentation coverage and markup

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

10 files changed, 103 insertions, 88 deletions

diff --git a/actionpack/lib/action_view/helpers/active_record_helper.rb b/actionpack/lib/action_view/helpers/active_record_helper.rb
index 7569cc381d..f3f204cc97 100644
--- a/actionpack/lib/action_view/helpers/active_record_helper.rb
+++ b/actionpack/lib/action_view/helpers/active_record_helper.rb
@@ -8,47 +8,55 @@ module ActionView
   end
 
   module Helpers
-    # The Active Record Helper makes it easier to create forms for records kept in instance variables. The most far-reaching is the form
+    # The Active Record Helper makes it easier to create forms for records kept in instance variables. The most far-reaching is the +form+
     # method that creates a complete form for all the basic content types of the record (not associations or aggregations, though). This
     # is a great way of making the record quickly available for editing, but likely to prove lackluster for a complicated real-world form.
-    # In that case, it's better to use the input method and the specialized form methods in link:classes/ActionView/Helpers/FormHelper.html
+    # In that case, it's better to use the +input+ method and the specialized +form+ methods in link:classes/ActionView/Helpers/FormHelper.html
     module ActiveRecordHelper
-      # Returns a default input tag for the type of object returned by the method. For example, let's say you have a model
-      # that has an attribute +title+ of type VARCHAR column, and this instance holds "Hello World":
-      #   input("post", "title") =>
-      #     <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
+      # Returns a default input tag for the type of object returned by the method. For example, if <tt>@post</tt>
+      # has an attribute +title+ mapped to a +VARCHAR+ column that holds "Hello World":
+      #
+      #   input("post", "title")
+      #   # => <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
       def input(record_name, method, options = {})
         InstanceTag.new(record_name, method, self).to_tag(options)
       end
 
-      # Returns an entire form with all needed input tags for a specified Active Record object. For example, let's say you 
-      # have a table model <tt>Post</tt> with attributes named <tt>title</tt> of type <tt>VARCHAR</tt> and <tt>body</tt> of type <tt>TEXT</tt>:
+      # Returns an entire form with all needed input tags for a specified Active Record object. For example, if <tt>@post</tt>
+      # has attributes named +title+ of type +VARCHAR+ and +body+ of type +TEXT+ then
+      #
       #   form("post") 
-      # That line would yield a form like the following:
-      #     <form action='/post/create' method='post'>
-      #       <p>
-      #         <label for="post_title">Title</label><br />
-      #         <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
-      #       </p>
-      #       <p>
-      #         <label for="post_body">Body</label><br />
-      #         <textarea cols="40" id="post_body" name="post[body]" rows="20">
-      #         </textarea>
-      #       </p>
-      #       <input type='submit' value='Create' />
-      #     </form>
+      #
+      # would yield a form like the following (modulus formatting):
+      #
+      #   <form action='/posts/create' method='post'>
+      #     <p>
+      #       <label for="post_title">Title</label><br />
+      #       <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
+      #     </p>
+      #     <p>
+      #       <label for="post_body">Body</label><br />
+      #       <textarea cols="40" id="post_body" name="post[body]" rows="20"></textarea>
+      #     </p>
+      #     <input name="commit" type="submit" value="Create" />
+      #   </form>
       #
       # It's possible to specialize the form builder by using a different action name and by supplying another
-      # block renderer. For example, let's say you have a model <tt>Entry</tt> with an attribute <tt>message</tt> of type <tt>VARCHAR</tt>:
+      # block renderer. For example, if <tt>@entry</tt> has an attribute +message+ of type +VARCHAR+ then
+      #
+      #   form("entry",
+      #     :action => "sign",
+      #     :input_block => Proc.new { |record, column|
+      #       "#{column.human_name}: #{input(record, column.name)}<br />"
+      #   })
       #
-      #   form("entry", :action => "sign", :input_block =>
-      #        Proc.new { |record, column| "#{column.human_name}: #{input(record, column.name)}<br />" }) =>
+      # would yield a form like the following (modulus formatting):
       #
-      #     <form action='/post/sign' method='post'>
-      #       Message:
-      #       <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /><br />
-      #       <input type='submit' value='Sign' />
-      #     </form>
+      #   <form action="/entries/sign" method="post">
+      #     Message:
+      #     <input id="entry_message" name="entry[message]" size="30" type="text" /><br />
+      #     <input name="commit" type="submit" value="Sign" />
+      #   </form>
       #
       # It's also possible to add additional content to the form by giving it a block, such as:
       #
@@ -59,11 +67,11 @@ module ActionView
       #
       # The following options are available:
       #
-      # * <tt>action</tt> - the action used when submitting the form (default: create if a new record, otherwise update)
-      # * <tt>input_block</tt> - specialize the output using a different block, see above
-      # * <tt>method</tt> - the method used when submitting the form (default: post)
-      # * <tt>multipart</tt> - whether to change the enctype of the form to multipart/form-date, used when uploading a file (default: false)
-      # * <tt>submit_value</tt> - the text of the submit button (default: Create if a new record, otherwise Update)
+      # * <tt>:action</tt> - The action used when submitting the form (default: +create+ if a new record, otherwise +update+).
+      # * <tt>:input_block</tt> - Specialize the output using a different block, see above.
+      # * <tt>:method</tt> - The method used when submitting the form (default: +post+).
+      # * <tt>:multipart</tt> - Whether to change the enctype of the form to "multipart/form-data", used when uploading a file (default: +false+).
+      # * <tt>:submit_value</tt> - The text of the submit button (default: "Create" if a new record, otherwise "Update").
       def form(record_name, options = {})
         record = instance_variable_get("@#{record_name}")
 
@@ -84,17 +92,16 @@ module ActionView
       # Returns a string containing the error message attached to the +method+ on the +object+ if one exists.
       # This error message is wrapped in a <tt>DIV</tt> tag, which can be extended to include a +prepend_text+ and/or +append_text+
       # (to properly explain the error), and a +css_class+ to style it accordingly. +object+ should either be the name of an instance variable or
-      # the actual object. As an example, let's say you have a model
-      # +post+ that has an error message on the +title+ attribute:
+      # the actual object. As an example, let's say you have a model <tt>@post</tt> that has an error message on the +title+ attribute:
       #
-      #   <%= error_message_on "post", "title" %> =>
-      #     <div class="formError">can't be empty</div>
+      #   <%= error_message_on "post", "title" %>
+      #   # => <div class="formError">can't be empty</div>
       #
-      #   <%= error_message_on @post, "title" %> =>
-      #     <div class="formError">can't be empty</div>
+      #   <%= error_message_on @post, "title" %>
+      #   # => <div class="formError">can't be empty</div>
       #
-      #   <%= error_message_on "post", "title", "Title simply ", " (or it won't work).", "inputError" %> =>
-      #     <div class="inputError">Title simply can't be empty (or it won't work).</div>
+      #   <%= error_message_on "post", "title", "Title simply ", " (or it won't work).", "inputError" %>
+      #   # => <div class="inputError">Title simply can't be empty (or it won't work).</div>
       def error_message_on(object, method, prepend_text = "", append_text = "", css_class = "formError")
         if (obj = (object.respond_to?(:errors) ? object : instance_variable_get("@#{object}"))) &&
           (errors = obj.errors.on(method))
@@ -110,30 +117,37 @@ module ActionView
       #
       # This <tt>DIV</tt> can be tailored by the following options:
       #
-      # * <tt>header_tag</tt> - Used for the header of the error div (default: h2)
-      # * <tt>id</tt> - The id of the error div (default: errorExplanation)
-      # * <tt>class</tt> - The class of the error div (default: errorExplanation)
-      # * <tt>object</tt> - The object (or array of objects) for which to display errors, if you need to escape the instance variable convention
-      # * <tt>object_name</tt> - The object name to use in the header, or any text that you prefer. If <tt>object_name</tt> is not set, the name of the first object will be used.
-      # * <tt>header_message</tt> - The message in the header of the error div.  Pass +nil+ or an empty string to avoid the header message altogether. (default: X errors prohibited this object from being saved)
-      # * <tt>message</tt> - The explanation message after the header message and before the error list.  Pass +nil+ or an empty string to avoid the explanation message altogether.  (default: There were problems with the following fields:)
+      # * <tt>:header_tag</tt> - Used for the header of the error div (default: "h2").
+      # * <tt>:id</tt> - The id of the error div (default: "errorExplanation").
+      # * <tt>:class</tt> - The class of the error div (default: "errorExplanation").
+      # * <tt>:object</tt> - The object (or array of objects) for which to display errors,
+      #   if you need to escape the instance variable convention.
+      # * <tt>:object_name</tt> - The object name to use in the header, or any text that you prefer.
+      #   If <tt>:object_name</tt> is not set, the name of the first object will be used.
+      # * <tt>:header_message</tt> - The message in the header of the error div.  Pass +nil+
+      #   or an empty string to avoid the header message altogether. (Default: "X errors
+      #   prohibited this object from being saved").
+      # * <tt>:message</tt> - The explanation message after the header message and before
+      #   the error list.  Pass +nil+ or an empty string to avoid the explanation message
+      #   altogether. (Default: "There were problems with the following fields:").
       #
-      # To specify the display for one object, you simply provide its name as a parameter.  For example, for the +User+ model:
+      # To specify the display for one object, you simply provide its name as a parameter.
+      # For example, for the <tt>@user</tt> model:
       # 
       #   error_messages_for 'user'
       #
-      # To specify more than one object, you simply list them; optionally, you can add an extra +object_name+ parameter, which
-      # will be the name used in the header message.
+      # To specify more than one object, you simply list them; optionally, you can add an extra <tt>:object_name</tt> parameter, which
+      # will be the name used in the header message:
       #
       #   error_messages_for 'user_common', 'user', :object_name => 'user'
       #
-      # If the objects cannot be located as instance variables, you can add an extra +object+ paremeter which gives the actual
-      # object (or array of objects to use)
+      # If the objects cannot be located as instance variables, you can add an extra <tt>:object</tt> paremeter which gives the actual
+      # object (or array of objects to use):
       #
       #   error_messages_for 'user', :object => @question.user
       #
       # NOTE: This is a pre-packaged presentation of the errors with embedded strings and a certain HTML structure. If what
-      # you need is significantly different from the default presentation, it makes plenty of sense to access the object.errors
+      # you need is significantly different from the default presentation, it makes plenty of sense to access the <tt>object.errors</tt>
       # instance yourself and set it up. View the source of this method to see how easy it is.
       def error_messages_for(*params)
         options = params.extract_options!.symbolize_keys
diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index 0cce96b184..dfc7e2b3ed 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -164,7 +164,7 @@ module ActionView
       # current page or you can pass the full path relative to your document
       # root. To include the Prototype and Scriptaculous javascript libraries in
       # your application, pass <tt>:defaults</tt> as the source. When using
-      # :defaults, if an <tt>application.js</tt> file exists in your public
+      # <tt>:defaults</tt>, if an application.js file exists in your public
       # javascripts directory, it will be included as well. You can modify the
       # html attributes of the script tag by passing a hash as the last argument.
       #
@@ -332,7 +332,7 @@ module ActionView
       #     <link href="/stylesheets/random.styles" media="screen" rel="stylesheet" type="text/css" />
       #     <link href="/css/stylish.css" media="screen" rel="stylesheet" type="text/css" />
       #
-      # You can also include all styles in the stylesheet directory using :all as the source:
+      # You can also include all styles in the stylesheet directory using <tt>:all</tt> as the source:
       #
       #   stylesheet_link_tag :all # =>
       #     <link href="/stylesheets/style1.css"  media="screen" rel="stylesheet" type="text/css" />
diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb
index 9f7790d0f9..cbd390421a 100755
--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/actionpack/lib/action_view/helpers/date_helper.rb
@@ -104,17 +104,17 @@ module ActionView
 
       # Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based attribute (identified by
       # +method+) on an object assigned to the template (identified by +object+). It's possible to tailor the selects through the +options+ hash,
-      # which accepts all the keys that each of the individual select builders do (like :use_month_numbers for select_month) as well as a range of
+      # which accepts all the keys that each of the individual select builders do (like <tt>:use_month_numbers</tt> for select_month) as well as a range of
       # discard options. The discard options are <tt>:discard_year</tt>, <tt>:discard_month</tt> and <tt>:discard_day</tt>. Set to true, they'll
       # drop the respective select. Discarding the month select will also automatically discard the day select. It's also possible to explicitly
       # set the order of the tags using the <tt>:order</tt> option with an array of symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in
       # the desired order. Symbols may be omitted and the respective select is not included.
       #
-      # Pass the <tt>:default</tt> option to set the default date. Use a Time object or a Hash of :year, :month, :day, :hour, :minute, and :second.
+      # Pass the <tt>:default</tt> option to set the default date. Use a Time object or a Hash of <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:minute</tt>, and <tt>:second</tt>.
       #
-      # Passing :disabled => true as part of the +options+ will make elements inaccessible for change.
+      # Passing <tt>:disabled => true</tt> as part of the +options+ will make elements inaccessible for change.
       #
-      # If anything is passed in the html_options hash it will be applied to every select tag in the set.
+      # If anything is passed in the +html_options+ hash it will be applied to every select tag in the set.
       #
       # NOTE: Discarded selects will default to 1. So if no month select is available, January will be assumed.
       #
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 65f4fb6e45..63c5fd57aa 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -108,7 +108,7 @@ module ActionView
       # Note: This also works for the methods in FormOptionHelper and DateHelper that are 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 :html => {...}. For example:
+      # 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| %>
       #     ...
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 5b026245da..bf65fe5574 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -93,8 +93,8 @@ module ActionView
       # This allows the user to submit a form page more than once with the expected results of creating multiple records.
       # In addition, this allows a single partial to be used to generate form inputs for both edit and create forms.
       #
-      # By default, post.person_id is the selected option.  Specify :selected => value to use a different selection
-      # or :selected => nil to leave all options unselected.
+      # By default, <tt>post.person_id</tt> is the selected option.  Specify <tt>:selected => value</tt> to use a different selection
+      # or <tt>:selected => nil</tt> to leave all options unselected.
       def select(object, method, choices, options = {}, html_options = {})
         InstanceTag.new(object, method, self, nil, options.delete(:object)).to_select_tag(choices, options, html_options)
       end
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 0544ed3ded..f37b428b80 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -341,8 +341,9 @@ module ActionView
       #   submit_tag nil, :class => "form_submit"
       #   # => <input class="form_submit" name="commit" type="submit" />
       #
-      #   submit_tag "Edit", :disable_with => "Editing...", :class => 'edit-button'
-      #   # => <input class="edit-button" disable_with="Editing..." name="commit" type="submit" value="Edit" />
+      #   submit_tag "Edit", :disable_with => "Editing...", :class => "edit-button"
+      #   # => <input class="edit-button" onclick="this.disabled=true;this.value='Editing...';this.form.submit();"
+      #   #    name="commit" type="submit" value="Edit" />
       def submit_tag(value = "Save changes", options = {})
         options.stringify_keys!
         
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index 81938ac8e3..908728c0e6 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -255,10 +255,10 @@ module ActionView
         link_to_function(name, remote_function(options), html_options || options.delete(:html))
       end
 
-      # Periodically calls the specified url (<tt>options[:url]</tt>) every 
+      # Periodically calls the specified url (<tt>options[:url]</tt>) every
       # <tt>options[:frequency]</tt> seconds (default is 10). Usually used to
-      # update a specified div (<tt>options[:update]</tt>) with the results 
-      # of the remote call. The options for specifying the target with :url 
+      # update a specified div (<tt>options[:update]</tt>) with the results
+      # of the remote call. The options for specifying the target with <tt>:url</tt>
       # and defining callbacks is the same as link_to_remote.
       # Examples:
       #  # Call get_averages and put its results in 'avg' every 10 seconds
@@ -291,11 +291,11 @@ module ActionView
       # though it's using JavaScript to serialize the form elements, the form
       # submission will work just like a regular submission as viewed by the
       # receiving side (all elements available in <tt>params</tt>). The options for 
-      # specifying the target with :url and defining callbacks is the same as
-      # link_to_remote.
+      # specifying the target with <tt>:url</tt> and defining callbacks is the same as
+      # +link_to_remote+.
       #
       # A "fall-through" target for browsers that doesn't do JavaScript can be
-      # specified with the :action/:method options on :html.
+      # specified with the <tt>:action</tt>/<tt>:method</tt> options on <tt>:html</tt>.
       #
       # Example:
       #   # Generates:
@@ -304,11 +304,11 @@ module ActionView
       #   form_remote_tag :html => { :action => 
       #     url_for(:controller => "some", :action => "place") }
       #
-      # The Hash passed to the :html key is equivalent to the options (2nd) 
+      # The Hash passed to the <tt>:html</tt> key is equivalent to the options (2nd)
       # argument in the FormTagHelper.form_tag method.
       #
       # By default the fall-through action is the same as the one specified in 
-      # the :url (and the default method is :post).
+      # the <tt>:url</tt> (and the default method is <tt>:post</tt>).
       #
       # form_remote_tag also takes a block, like form_tag:
       #   # Generates:
@@ -422,8 +422,8 @@ module ActionView
       end
       
       # Returns '<tt>eval(request.responseText)</tt>' which is the JavaScript function
-      # that form_remote_tag can call in :complete to evaluate a multiple
-      # update return document using update_element_function calls.
+      # that +form_remote_tag+ can call in <tt>:complete</tt> to evaluate a multiple
+      # update return document using +update_element_function+ calls.
       def evaluate_remote_response
         "eval(request.responseText)"
       end
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index 47fbe3a27a..3129ff414e 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -10,7 +10,7 @@ module ActionView
         base.extend(ClassMethods)
       end
       
-      # This #sanitize helper will html encode all tags and strip all attributes that aren't specifically allowed.  
+      # This +sanitize+ helper will html encode all tags and strip all attributes that aren't specifically allowed.
       # It also strips href/src tags with invalid protocols, like javascript: especially.  It does its best to counter any
       # tricks that hackers may use, like throwing in unicode/ascii/hex values to get past the javascript: filters.  Check out
       # the extensive test suite.
@@ -18,7 +18,7 @@ module ActionView
       #   <%= sanitize @article.body %>
       # 
       # You can add or remove tags/attributes if you want to customize it a bit.  See ActionView::Base for full docs on the
-      # available options.  You can add tags/attributes for single uses of #sanitize by passing either the :attributes or :tags options:
+      # available options.  You can add tags/attributes for single uses of +sanitize+ by passing either the <tt>:attributes</tt> or <tt>:tags</tt> options:
       #
       # Normal Use
       #
diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
index 60e285b722..12b4cfd3f8 100644
--- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
+++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
@@ -35,8 +35,8 @@ module ActionView
       # This would fade the element that was dropped on the drop receiving 
       # element.
       #
-      # For toggling visual effects, you can use :toggle_appear, :toggle_slide, and
-      # :toggle_blind which will alternate between appear/fade, slidedown/slideup, and
+      # For toggling visual effects, you can use <tt>:toggle_appear</tt>, <tt>:toggle_slide</tt>, and
+      # <tt>:toggle_blind</tt> which will alternate between appear/fade, slidedown/slideup, and
       # blinddown/blindup respectively.
       #
       # You can change the behaviour with various options, see
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 4a951f2c88..6d27494213 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -16,7 +16,7 @@ module ActionView
       # instead of the fully qualified URL like http://example.com/controller/action.
       #
       # When called from a view, url_for returns an HTML escaped url. If you
-      # need an unescaped url, pass :escape => false in the +options+.
+      # need an unescaped url, pass <tt>:escape => false</tt> in the +options+.
       #
       # ==== Options
       # * <tt>:anchor</tt> -- specifies the anchor name to be appended to the path.
@@ -25,8 +25,8 @@ module ActionView
       #   is currently not recommended since it breaks caching.
       # * <tt>:host</tt> -- overrides the default (current) host if provided
       # * <tt>:protocol</tt> -- overrides the default (current) protocol if provided
-      # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if :password is also present)
-      # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if :user is also present)
+      # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present)
+      # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present)
       # * <tt>:escape</tt> -- Determines whether the returned URL will be HTML escaped or not (<tt>true</tt> by default)
       #
       # ==== Relying on named routes
@@ -102,21 +102,21 @@ module ActionView
       #   create an HTML form and immediately submit the form for processing using
       #   the HTTP verb specified. Useful for having links perform a POST operation
       #   in dangerous actions like deleting a record (which search bots can follow
-      #   while spidering your site). Supported verbs are :post, :delete and :put.
+      #   while spidering your site). Supported verbs are <tt>:post</tt>, <tt>:delete</tt> and <tt>:put</tt>.
       #   Note that if the user has JavaScript disabled, the request will fall back
       #   to using GET. If you are relying on the POST behavior, you should check
       #   for it in your controller's action by using the request object's methods
-      #   for post?, delete? or put?.
+      #   for <tt>post?</tt>, <tt>delete?</tt> or <tt>put?</tt>.
       # * The +html_options+ will accept a hash of html attributes for the link tag.
       #
       # Note that if the user has JavaScript disabled, the request will fall back
-      # to using GET. If :href=>'#' is used and the user has JavaScript disabled
+      # to using GET. If <tt>:href => '#'</tt> is used and the user has JavaScript disabled
       # clicking the link will have no effect. If you are relying on the POST 
       # behavior, your should check for it in your controller's action by using the 
-      # request object's methods for post?, delete? or put?. 
+      # request object's methods for <tt>post?</tt>, <tt>delete?</tt> or <tt>put?</tt>.
       #
       # You can mix and match the +html_options+ with the exception of
-      # :popup and :method which will raise an ActionView::ActionViewError
+      # <tt>:popup</tt> and <tt>:method</tt> which will raise an ActionView::ActionViewError
       # exception.
       #
       # ==== Examples