Improve documentation.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

4 files changed, 20 insertions, 9 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 303ef75977..80decb7413 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert]
+
 * Fixed that FormHelper#radio_button would produce invalid ids #11298 [harlancrystal]
 
 * Added :confirm option to submit_tag #11415 [miloops]
diff --git a/actionpack/lib/action_controller/resources.rb b/actionpack/lib/action_controller/resources.rb
index 20fa3b9904..2cc01f61dc 100644
--- a/actionpack/lib/action_controller/resources.rb
+++ b/actionpack/lib/action_controller/resources.rb
@@ -227,6 +227,13 @@ module ActionController
     #
     #   <% form_for :message, @message, :url => message_path(@message), :html => {:method => :put} do |f| %>
     #
+    # or
+    #
+    #   <% form_for @message do |f| %>
+    #
+    # which takes into account whether <tt>@message</tt> is a new record or not and generates the
+    # path and method accordingly.
+    #
     # The #resources method accepts the following options to customize the resulting routes:
     # * <tt>:collection</tt> - add named routes for other actions that operate on the collection.
     #   Takes a hash of <tt>#{action} => #{method}</tt>, where method is <tt>:get</tt>/<tt>:post</tt>/<tt>:put</tt>/<tt>:delete</tt>
diff --git a/actionpack/lib/action_view/helpers/atom_feed_helper.rb b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
index 5aaf1b4688..ebb1cb34bc 100644
--- a/actionpack/lib/action_view/helpers/atom_feed_helper.rb
+++ b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
@@ -49,7 +49,7 @@ module ActionView
       # * <tt>:url</tt>: The URL for this feed. Defaults to the current URL.
       # * <tt>:schema_date</tt>: The date at which the tag scheme for the feed was first used. A good default is the year you 
       #   created the feed. See http://feedvalidator.org/docs/error/InvalidTAG.html for more information. If not specified, 
-      #   2005 is used (as a "I don't care"-value).
+      #   2005 is used (as an "I don't care" value).
       #
       # Other namespaces can be added to the root element:
       #
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 22c6562cc7..0e77a7e067 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -76,6 +76,7 @@ module ActionView
       # values for the fields.
       #
       #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
+      #     <%= f.error_messages %>
       #     First name: <%= f.text_field :first_name %>
       #     Last name : <%= f.text_field :last_name %>
       #     Biography : <%= f.text_area :biography %>
@@ -85,7 +86,8 @@ module ActionView
       # 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>.
+      # 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>
@@ -405,7 +407,7 @@ module ActionView
       # ==== 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":
@@ -413,8 +415,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")
@@ -430,13 +432,13 @@ 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