Add basic documentation to collection_check_boxes and

collection_radio_buttons

[Carlos Antonio da Silva + Rafael Mendonça França]

1 files changed, 71 insertions, 0 deletions

diff --git a/actionpack/lib/action_view/helpers/form_collections_helper.rb b/actionpack/lib/action_view/helpers/form_collections_helper.rb
index 9280902e7c..da89a23552 100644
--- a/actionpack/lib/action_view/helpers/form_collections_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_collections_helper.rb
@@ -1,10 +1,81 @@
 module ActionView
   module Helpers
     module FormCollectionsHelper
+      # Returns radio button tags for the collection of existing return values of +method+ for
+      # +object+'s class. The value returned from calling +method+ on the instance +object+ will
+      # be selected. If calling +method+ returns +nil+, no selection is made.
+      #
+      # The <tt>:value_method</tt> and <tt>:text_method</tt> parameters are methods to be called on each member
+      # of +collection+. The return values are used as the +value+ attribute and contents of each
+      # radio button tag, respectively.
+      #
+      # Example object structure for use with this method:
+      #   class Post < ActiveRecord::Base
+      #     belongs_to :author
+      #   end
+      #   class Author < ActiveRecord::Base
+      #     has_many :posts
+      #     def name_with_initial
+      #       "#{first_name.first}. #{last_name}"
+      #     end
+      #   end
+      #
+      # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
+      #   collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial)
+      #
+      # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
+      #   <span>
+      #     <input id="post_author_id_1" name="post[author_id]" type="radio" value="1" checked="checked" />
+      #     <label class="collection_radio_buttons" for="post_author_id_1">D. Heinemeier Hansson</label>
+      #   </span>
+      #   <span>
+      #     <input id="post_author_id_2" name="post[author_id]" type="radio" value="2" />
+      #     <label class="collection_radio_buttons" for="post_author_id_2">D. Thomas</label>
+      #   </span>
+      #   <span>
+      #     <input id="post_author_id_3" name="post[author_id]" type="radio" value="3" />
+      #     <label class="collection_radio_buttons" for="post_author_id_3">M. Clark</label>
+      #   </span>
       def collection_radio_buttons(object, method, collection, value_method, text_method, options = {}, html_options = {}, &block)
         Tags::CollectionRadioButtons.new(object, method, self, collection, value_method, text_method, options, html_options).render(&block)
       end
 
+      # Returns check box tags for the collection of existing return values of +method+ # for
+      # +object+'s class. The value returned from calling +method+ on the instance +object+ will
+      # be selected. If calling +method+ returns +nil+, no selection is made.
+      #
+      # The <tt>:value_method</tt> and <tt>:text_method</tt> parameters are methods to be called on each member
+      # of +collection+. The return values are used as the +value+ attribute and contents of each
+      # check box tag, respectively.
+      #
+      # Example object structure for use with this method:
+      #   class Post < ActiveRecord::Base
+      #     has_and_belongs_to :author
+      #   end
+      #   class Author < ActiveRecord::Base
+      #     has_and_belongs_to :posts
+      #     def name_with_initial
+      #       "#{first_name.first}. #{last_name}"
+      #     end
+      #   end
+      #
+      # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
+      #   collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial)
+      #
+      # If <tt>@post.author_ids</tt> is already <tt>[1]</tt>, this would return:
+      #   <span>
+      #     <input id="post_author_ids_1" name="post[author_ids][]" type="checkbox" value="1" checked="checked" />
+      #     <label class="collection_check_boxes" for="post_author_ids_1">D. Heinemeier Hansson</label>
+      #   </span>
+      #   <span>
+      #     <input id="post_author_ids_1" name="post[author_ids][]" type="checkbox" value="2" />
+      #     <label class="collection_check_boxes" for="post_author_ids_1">D. Thomas</label>
+      #   </span>
+      #   <span>
+      #     <input id="post_author_ids_3" name="post[author_ids][]" type="checkbox" value="3" />
+      #     <label class="collection_check_boxes" for="post_author_ids_3">M. Clark</label>
+      #   </span>
+      #   <input name="post[author_ids][]" type="hidden" value="" />
       def collection_check_boxes(object, method, collection, value_method, text_method, options = {}, html_options = {}, &block)
         Tags::CollectionCheckBoxes.new(object, method, self, collection, value_method, text_method, options, html_options).render(&block)
       end