actionpack 2.0.5 → 2.1.0

data/lib/action_view/helpers/form_helper.rb

@@ -1,6 +1,7 @@
 require 'cgi'
 require 'action_view/helpers/date_helper'
 require 'action_view/helpers/tag_helper'
+require 'action_view/helpers/form_tag_helper'
 
 module ActionView
   module Helpers
@@ -32,6 +33,15 @@ module ActionView
     #       <input name="commit" type="submit" value="Create" />
     #     </form>
     #
+    # If you are using a partial for your form fields, you can use this shortcut:
+    #
+    #     <% form_for :person, @person, :url => { :action => "create" } do |f| %>
+    #       <%= render :partial => f %>
+    #       <%= submit_tag 'Create' %>
+    #     <% end %>
+    #
+    # This example will render the <tt>people/_form</tt> partial, setting a local variable called <tt>form</tt> which references the yielded FormBuilder.
+    #
     # The <tt>params</tt> object created when this form is submitted would look like:
     #
     #     {"action"=>"create", "controller"=>"persons", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}}
@@ -42,7 +52,7 @@ module ActionView
     #
     # If the object name contains square brackets the id for the object will be inserted. For example:
     #
-    #   <%= text_field "person[]", "name" %> 
+    #   <%= text_field "person[]", "name" %>
     #
     # ...will generate the following ERb.
     #
@@ -57,31 +67,87 @@ module ActionView
     #
     #   <input type="text" id="person_1_name" name="person[1][name]" value="<%= @person.name %>" />
     #
+    # An <tt>index</tt> option may also be passed to <tt>form_for</tt> and <tt>fields_for</tt>.  This automatically applies
+    # the <tt>index</tt> to all the nested fields.
+    #
     # There are also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html,
     # link:classes/ActionView/Helpers/DateHelper.html, and link:classes/ActionView/Helpers/ActiveRecordHelper.html
     module FormHelper
-      # Creates a form and a scope around a specific model object that is used as a base for questioning about
-      # values for the fields.
+      # Creates a form and a scope around a specific model object that is used as
+      # a base for questioning about values for the fields.
       #
-      #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
-      #     First name: <%= f.text_field :first_name %>
-      #     Last name : <%= f.text_field :last_name %>
-      #     Biography : <%= f.text_area :biography %>
-      #     Admin?    : <%= f.check_box :admin %>
+      # Rails provides succint resource-oriented form generation with +form_for+
+      # like this:
+      #
+      #   <% form_for @offer do |f| %>
+      #     <%= f.label :version, 'Version' %>:
+      #     <%= f.text_field :version %><br />
+      #     <%= f.label :author, 'Author' %>:
+      #     <%= f.text_field :author %><br />
+      #   <% end %>
+      #
+      # 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+ yields a form builder around a model:
+      #
+      #   <% 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 />
+      #     Biography : <%= f.text_area :biography %><br />
+      #     Admin?    : <%= f.check_box :admin %><br />
       #   <% end %>
       #
-      # 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 <tt>form_builder</tt> object, in this example as <tt>f</tt>, 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>.
+      # 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 %>
       #
-      # 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>.
+      # gets expanded to
       #
-      # 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 FormTagHelper. For example:
+      #   <%= 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 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
+      # FormTagHelper. For example:
       #
       #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
       #     First name: <%= f.text_field :first_name %>
@@ -90,42 +156,38 @@ module ActionView
       #     Admin?    : <%= check_box_tag "person[admin]", @person.company.admin? %>
       #   <% end %>
       #
-      # 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:
-      #
-      #   <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
-      #     ...
-      #   <% end %>
+      # 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.
       #
-      # The above form will then have the <tt>id</tt> attribute with the value </tt>person_form</tt>, which you can then
-      # style with CSS or manipulate with JavaScript.
+      # === Resource-oriented style
       #
-      # === Relying on record identification
+      # As we said above, in addition to manually configuring the +form_for+ call,
+      # 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.
       #
-      # In addition to manually configuring the form_for call, you can also rely on record identification, which will use
-      # the conventions and named routes of that approach. Examples:
+      # 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, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
+      #   <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
       #     ...
       #   <% end %>
       #
@@ -135,7 +197,7 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # And for namespaced routes, like admin_post_url: 
+      # And for namespaced routes, like +admin_post_url+:
       #
       #   <% form_for([:admin, @post]) do |f| %>
       #    ...
@@ -153,6 +215,12 @@ module ActionView
       #     <%= check_box_tag "person[admin]", @person.company.admin? %>
       #   <% end %>
       #
+      # In this case, if you use this:
+      #
+      #   <%= render :partial => f %>
+      #
+      # The rendered template is <tt>people/_labelling_form</tt> and the local variable referencing the form builder is called <tt>labelling_form</tt>.
+      #
       # In many cases you will want to wrap the above in another helper, so you could do something like the following:
       #
       #   def labelled_form_for(record_or_name_or_array, *args, &proc)
@@ -256,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)
@@ -317,7 +385,7 @@ module ActionView
       # hash with +options+. These options will be tagged onto the HTML as an HTML element attribute as in the example
       # shown.
       #
-      # ==== Examples 
+      # ==== Examples
       #   hidden_field(:signup, :pass_confirm)
       #   # => <input type="hidden" id="signup_pass_confirm" name="signup[pass_confirm]" value="#{@signup.pass_confirm}" />
       #
@@ -384,10 +452,10 @@ module ActionView
       # is set to 0 which is convenient for boolean values. Since HTTP standards say that unchecked checkboxes don't post anything,
       # we add a hidden value with the same name as the checkbox as a work around.
       #
-      # ==== Examples 
+      # ==== Examples
       #   # Let's say that @post.validated? is 1:
       #   check_box("post", "validated")
-      #   # => <input type="checkbox" id="post_validate" name="post[validated]" value="1" checked="checked" />
+      #   # => <input type="checkbox" id="post_validated" name="post[validated]" value="1" />
       #   #    <input name="post[validated]" type="hidden" value="0" />
       #
       #   # Let's say that @puppy.gooddog is "no":
@@ -395,8 +463,8 @@ module ActionView
       #   # => <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
       #   #    <input name="puppy[gooddog]" type="hidden" value="no" />
       #
-      #   check_box("eula", "accepted", {}, "yes", "no", :class => 'eula_check')
-      #   # => <input type="checkbox" id="eula_accepted" name="eula[accepted]" value="no" />
+      #   check_box("eula", "accepted", { :class => 'eula_check' }, "yes", "no")
+      #   # => <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />
       #   #    <input name="eula[accepted]" type="hidden" value="no" />
       #
       def check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")
@@ -412,27 +480,26 @@ module ActionView
       #   # Let's say that @post.category returns "rails":
       #   radio_button("post", "category", "rails")
       #   radio_button("post", "category", "java")
-      #   # => <input type="radio" id="post_category" name="post[category]" value="rails" checked="checked" />
-      #   #    <input type="radio" id="post_category" name="post[category]" value="java" />
+      #   # => <input type="radio" id="post_category_rails" name="post[category]" value="rails" checked="checked" />
+      #   #    <input type="radio" id="post_category_java" name="post[category]" value="java" />
       #
       #   radio_button("user", "receive_newsletter", "yes")
       #   radio_button("user", "receive_newsletter", "no")
-      #   # => <input type="radio" id="user_receive_newsletter" name="user[receive_newsletter]" value="yes" />
-      #   #    <input type="radio" id="user_receive_newsletter" name="user[receive_newsletter]" value="no" checked="checked" />
+      #   # => <input type="radio" id="user_receive_newsletter_yes" name="user[receive_newsletter]" value="yes" />
+      #   #    <input type="radio" id="user_receive_newsletter_no" name="user[receive_newsletter]" value="no" checked="checked" />
       def radio_button(object_name, method, tag_value, options = {})
         InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_radio_button_tag(tag_value, options)
       end
     end
 
     class InstanceTag #:nodoc:
-      include Helpers::TagHelper
+      include Helpers::TagHelper, Helpers::FormTagHelper
 
       attr_reader :method_name, :object_name
 
       DEFAULT_FIELD_OPTIONS     = { "size" => 30 }.freeze unless const_defined?(:DEFAULT_FIELD_OPTIONS)
       DEFAULT_RADIO_OPTIONS     = { }.freeze unless const_defined?(:DEFAULT_RADIO_OPTIONS)
       DEFAULT_TEXT_AREA_OPTIONS = { "cols" => 40, "rows" => 20 }.freeze unless const_defined?(:DEFAULT_TEXT_AREA_OPTIONS)
-      DEFAULT_DATE_OPTIONS = { :discard_type => true }.freeze unless const_defined?(:DEFAULT_DATE_OPTIONS)
 
       def initialize(object_name, method_name, template_object, local_binding = nil, object = nil)
         @object_name, @method_name = object_name.to_s.dup, method_name.to_s.dup
@@ -448,11 +515,13 @@ module ActionView
       end
 
       def to_label_tag(text = nil, options = {})
+        options = options.stringify_keys
         name_and_id = options.dup
         add_default_name_and_id(name_and_id)
-        options["for"] = name_and_id["id"]
+        options.delete("index")
+        options["for"] ||= name_and_id["id"]
         content = (text.blank? ? nil : text.to_s) || method_name.humanize
-        content_tag("label", content, options)
+        label_tag(name_and_id["id"], content, options)
       end
 
       def to_input_field_tag(field_type, options = {})
@@ -464,6 +533,7 @@ module ActionView
         end
         options["type"] = field_type
         options["value"] ||= value_before_type_cast(object) unless field_type == "file"
+        options["value"] &&= html_escape(options["value"])
         add_default_name_and_id(options)
         tag("input", options)
       end
@@ -481,8 +551,8 @@ module ActionView
         options["checked"]  = "checked" if checked
         pretty_tag_value    = tag_value.to_s.gsub(/\s/, "_").gsub(/\W/, "").downcase
         options["id"]     ||= defined?(@auto_index) ?
-          "#{@object_name}_#{@auto_index}_#{@method_name}_#{pretty_tag_value}" :
-          "#{@object_name}_#{@method_name}_#{pretty_tag_value}"
+          "#{tag_id_with_index(@auto_index)}_#{pretty_tag_value}" :
+          "#{tag_id}_#{pretty_tag_value}"
         add_default_name_and_id(options)
         tag("input", options)
       end
@@ -513,15 +583,6 @@ module ActionView
         tag("input", options) << tag("input", "name" => options["name"], "type" => "hidden", "value" => options['disabled'] && checked ? checked_value : unchecked_value)
       end
 
-      def to_date_tag()
-        defaults = DEFAULT_DATE_OPTIONS.dup
-        date     = value(object) || Date.today
-        options  = Proc.new { |position| defaults.merge(:prefix => "#{@object_name}[#{@method_name}(#{position}i)]") }
-        html_day_select(date, options.call(3)) +
-        html_month_select(date, options.call(2)) +
-        html_year_select(date, options.call(1))
-      end
-
       def to_boolean_select_tag(options = {})
         options = options.stringify_keys
         add_default_name_and_id(options)
@@ -574,6 +635,8 @@ module ActionView
             value != 0
           when String
             value == checked_value
+          when Array
+            value.include?(checked_value)
           else
             value.to_i != 0
           end
@@ -600,23 +663,27 @@ module ActionView
         end
 
         def tag_name
-          "#{@object_name}[#{@method_name}]"
+          "#{@object_name}[#{sanitized_method_name}]"
         end
 
         def tag_name_with_index(index)
-          "#{@object_name}[#{index}][#{@method_name}]"
+          "#{@object_name}[#{index}][#{sanitized_method_name}]"
         end
 
         def tag_id
-          "#{sanitized_object_name}_#{@method_name}"
+          "#{sanitized_object_name}_#{sanitized_method_name}"
         end
 
         def tag_id_with_index(index)
-          "#{sanitized_object_name}_#{index}_#{@method_name}"
+          "#{sanitized_object_name}_#{index}_#{sanitized_method_name}"
         end
 
         def sanitized_object_name
-          @object_name.gsub(/[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+          @sanitized_object_name ||= @object_name.gsub(/[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
+        end
+
+        def sanitized_method_name
+          @sanitized_method_name ||= @method_name.sub(/\?$/,"")
         end
     end
 
@@ -629,12 +696,13 @@ module ActionView
 
       def initialize(object_name, object, template, options, proc)
         @object_name, @object, @template, @options, @proc = object_name, object, template, options, proc
+        @default_options = @options ? @options.slice(:index) : {}
       end
 
       (field_helpers - %w(label check_box radio_button fields_for)).each do |selector|
         src = <<-end_src
           def #{selector}(method, options = {})
-            @template.send(#{selector.inspect}, @object_name, method, options.merge(:object => @object))
+            @template.send(#{selector.inspect}, @object_name, method, objectify_options(options))
           end
         end_src
         class_eval src, __FILE__, __LINE__
@@ -653,20 +721,20 @@ module ActionView
           name = "#{object_name}[#{ActionController::RecordIdentifier.singular_class_name(object)}]"
           args.unshift(object)
         end
-        
+
         @template.fields_for(name, *args, &block)
       end
 
       def label(method, text = nil, options = {})
-        @template.label(@object_name, method, text, options.merge(:object => @object))
+        @template.label(@object_name, method, text, objectify_options(options))
       end
 
       def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
-        @template.check_box(@object_name, method, options.merge(:object => @object), checked_value, unchecked_value)
+        @template.check_box(@object_name, method, objectify_options(options), checked_value, unchecked_value)
       end
 
       def radio_button(method, tag_value, options = {})
-        @template.radio_button(@object_name, method, tag_value, options.merge(:object => @object))
+        @template.radio_button(@object_name, method, tag_value, objectify_options(options))
       end
 
       def error_message_on(method, prepend_text = "", append_text = "", css_class = "formError")
@@ -674,12 +742,17 @@ module ActionView
       end
 
       def error_messages(options = {})
-        @template.error_messages_for(@object_name, options.merge(:object => @object))
+        @template.error_messages_for(@object_name, objectify_options(options))
       end
 
       def submit(value = "Save changes", options = {})
         @template.submit_tag(value, options.reverse_merge(:id => "#{object_name}_submit"))
       end
+
+      private
+        def objectify_options(options)
+          @default_options.merge(options.merge(:object => @object))
+        end
     end
   end
 

data/lib/action_view/helpers/form_options_helper.rb

@@ -53,6 +53,21 @@ module ActionView
     #     <option value="2">Sam</option>
     #     <option value="3">Tobias</option>
     #   </select>
+    # 
+    # Like the other form helpers, +select+ can accept an <tt>:index</tt> option to manually set the ID used in the resulting output. Unlike other helpers, +select+ expects this 
+    # option to be in the +html_options+ parameter.
+    # 
+    # Example: 
+    # 
+    #   select("album[]", "genre", %w[rap rock country], {}, { :index => nil })
+    # 
+    # becomes:
+    # 
+    #   <select name="album[][genre]" id="album__genre">
+    #     <option value="rap">rap</option>
+    #     <option value="rock">rock</option>
+    #     <option value="country">country</option>
+    #   </select>
     module FormOptionsHelper
       include ERB::Util
 
@@ -78,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
@@ -104,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:
@@ -129,10 +144,16 @@ 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
+      # as +priority_zones+, so that they will be listed above the rest of the
+      # (long) list. (You can use TimeZone.us_zones as a convenience for
+      # 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)
@@ -141,6 +162,8 @@ module ActionView
       #
       #   time_zone_select( "user", 'time_zone', TimeZone.us_zones, :default => "Pacific Time (US & Canada)")
       #
+      #   time_zone_select( "user", 'time_zone', [ TimeZone['Alaska'], TimeZone['Hawaii'] ])
+      #
       #   time_zone_select( "user", "time_zone", TZInfo::Timezone.all.sort, :model => TZInfo::Timezone)
       def time_zone_select(object, method, priority_zones = nil, options = {}, html_options = {})
         InstanceTag.new(object, method, self, nil, options.delete(:object)).to_time_zone_select_tag(priority_zones, options, html_options)
@@ -149,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):
@@ -194,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
@@ -277,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