Merge remote branch 'origin/master'

20 files changed, 70 insertions, 23 deletions

diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index 25426a5547..d094b0d8d8 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -6,6 +6,7 @@ require 'active_support/core_ext/file'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Asset Tag Helpers
   module Helpers #:nodoc:
     # This module provides methods for generating HTML that links views to assets such
     # as images, javascripts, stylesheets, and feeds. These methods do not verify
diff --git a/actionpack/lib/action_view/helpers/atom_feed_helper.rb b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
index 52806f206a..cb5a1404ff 100644
--- a/actionpack/lib/action_view/helpers/atom_feed_helper.rb
+++ b/actionpack/lib/action_view/helpers/atom_feed_helper.rb
@@ -1,10 +1,12 @@
 require 'set'
 
-# Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERb or any other
-# template languages).
 module ActionView
+  # = Action View Atom Feed Helpers
   module Helpers #:nodoc:
     module AtomFeedHelper
+      # Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERb or any other
+      # template languages).
+      #
       # Full usage example:
       #
       #   config/routes.rb:
diff --git a/actionpack/lib/action_view/helpers/cache_helper.rb b/actionpack/lib/action_view/helpers/cache_helper.rb
index 8251ed18f4..f544a9d147 100644
--- a/actionpack/lib/action_view/helpers/cache_helper.rb
+++ b/actionpack/lib/action_view/helpers/cache_helper.rb
@@ -1,8 +1,10 @@
 module ActionView
+  # = Action View Cache Helper
   module Helpers
-    # This helper to exposes a method for caching of view fragments.
-    # See ActionController::Caching::Fragments for usage instructions.
     module CacheHelper
+      # This helper to exposes a method for caching of view fragments.
+      # See ActionController::Caching::Fragments for usage instructions.
+      #
       # A method for caching fragments of a view rather than an entire
       # action or page.  This technique is useful caching pieces like
       # menus, lists of news topics, static HTML fragments, and so on.
diff --git a/actionpack/lib/action_view/helpers/capture_helper.rb b/actionpack/lib/action_view/helpers/capture_helper.rb
index edc6afc622..ea1bf14c96 100644
--- a/actionpack/lib/action_view/helpers/capture_helper.rb
+++ b/actionpack/lib/action_view/helpers/capture_helper.rb
@@ -1,9 +1,11 @@
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Capture Helper
   module Helpers
     # CaptureHelper exposes methods to let you extract generated markup which
     # can be used in other parts of a template or layout file.
+    #
     # It provides a method to capture blocks into variables through capture and
     # a way to capture a block of markup for use in a layout through content_for.
     module CaptureHelper
diff --git a/actionpack/lib/action_view/helpers/csrf_helper.rb b/actionpack/lib/action_view/helpers/csrf_helper.rb
index 41c6b67f91..3d03f6aac6 100644
--- a/actionpack/lib/action_view/helpers/csrf_helper.rb
+++ b/actionpack/lib/action_view/helpers/csrf_helper.rb
@@ -1,7 +1,9 @@
 module ActionView
+  # = Action View CSRF Helper
   module Helpers
     module CsrfHelper
-      # Returns a meta tag with the request forgery protection token for forms to use. Put this in your head.
+      # Returns a meta tag with the cross-site request forgery protection token
+      # for forms to use. Place this in your head.
       def csrf_meta_tag
         if protect_against_forgery?
           %(<meta name="csrf-param" content="#{Rack::Utils.escape_html(request_forgery_protection_token)}"/>\n<meta name="csrf-token" content="#{Rack::Utils.escape_html(form_authenticity_token)}"/>).html_safe
diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb
index 7d846a01dd..6f387bc95a 100644
--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/actionpack/lib/action_view/helpers/date_helper.rb
@@ -4,6 +4,8 @@ require 'active_support/core_ext/hash/slice'
 
 module ActionView
   module Helpers
+    # = Action View Date Helpers
+    #
     # The Date Helper primarily creates select/option tags for different kinds of dates and date elements. All of the
     # select-type methods share a number of common options that are as follows:
     #
diff --git a/actionpack/lib/action_view/helpers/debug_helper.rb b/actionpack/lib/action_view/helpers/debug_helper.rb
index e637dc1474..1491cb073f 100644
--- a/actionpack/lib/action_view/helpers/debug_helper.rb
+++ b/actionpack/lib/action_view/helpers/debug_helper.rb
@@ -1,6 +1,8 @@
 module ActionView
+  # = Action View Debug Helper
+  # 
+  # Provides a set of methods for making it easier to debug Rails objects.
   module Helpers
-    # Provides a set of methods for making it easier to debug Rails objects.
     module DebugHelper
       # Returns a YAML representation of +object+ wrapped with <pre> and </pre>.
       # If the object cannot be converted to YAML using +to_yaml+, +inspect+ will be called instead.
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 9e2448fe97..a8887a804e 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -7,6 +7,7 @@ require 'active_support/core_ext/hash/slice'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Helpers
   module Helpers
     # Form helpers are designed to make working with resources much easier
     # compared to using vanilla HTML.
diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb
index 6bf78647ec..c564d30302 100644
--- a/actionpack/lib/action_view/helpers/form_options_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_options_helper.rb
@@ -4,6 +4,7 @@ require 'action_view/helpers/form_helper'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Option Helpers
   module Helpers
     # Provides a number of methods for turning different kinds of containers into a set of option tags.
     # == Options
diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index 0727375fc0..ea491b2db8 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/object/returning'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Form Tag Helpers
   module Helpers
     # 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.
diff --git a/actionpack/lib/action_view/helpers/javascript_helper.rb b/actionpack/lib/action_view/helpers/javascript_helper.rb
index b0a7718f22..84f53b842c 100644
--- a/actionpack/lib/action_view/helpers/javascript_helper.rb
+++ b/actionpack/lib/action_view/helpers/javascript_helper.rb
@@ -1,6 +1,7 @@
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View JavaScript Helpers
   module Helpers
     # Provides functionality for working with JavaScript in your views.
     #
diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb
index a798c3eaef..3038b07143 100644
--- a/actionpack/lib/action_view/helpers/prototype_helper.rb
+++ b/actionpack/lib/action_view/helpers/prototype_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/object/returning'
 require 'active_support/core_ext/object/blank'
 
 module ActionView
+  # = Action View Prototype Helpers
   module Helpers
     # Prototype[http://www.prototypejs.org/] is a JavaScript library that provides
     # DOM[http://en.wikipedia.org/wiki/Document_Object_Model] manipulation,
diff --git a/actionpack/lib/action_view/helpers/raw_output_helper.rb b/actionpack/lib/action_view/helpers/raw_output_helper.rb
index 8c7f41177d..da7599fa8f 100644
--- a/actionpack/lib/action_view/helpers/raw_output_helper.rb
+++ b/actionpack/lib/action_view/helpers/raw_output_helper.rb
@@ -1,6 +1,15 @@
 module ActionView #:nodoc:
+  # = Action View Raw Output Helper
   module Helpers #:nodoc:
     module RawOutputHelper
+      # This method outputs without escaping a string. Since escaping tags is 
+      # now default, this can be used when you don't want Rails to automatically
+      # escape tags. This is not recommended if the data is coming from the user's
+      # input.
+      #
+      # For example:
+      #
+      # <%=raw @user.name %>
       def raw(stringish)
         stringish.to_s.html_safe
       end
diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb
index a9cf15f418..7433f08777 100644
--- a/actionpack/lib/action_view/helpers/record_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb
@@ -1,4 +1,5 @@
 module ActionView
+  # = Action View Record Tag Helpers
   module Helpers
     module RecordTagHelper
       # Produces a wrapper DIV element with id and class parameters that
diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb
index f173523f6a..b47818a22a 100644
--- a/actionpack/lib/action_view/helpers/sanitize_helper.rb
+++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb
@@ -2,19 +2,25 @@ require 'action_controller/vendor/html-scanner'
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Sanitize Helpers
   module Helpers #:nodoc:
     # The SanitizeHelper module provides a set of methods for scrubbing text of undesired HTML elements.
     # These helper methods extend Action View making them callable within your template files.
     module SanitizeHelper
-      # 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
+      # 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.
       #
       #   <%= 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 <tt>:attributes</tt> or <tt>:tags</tt> options:
+      # 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 
+      # <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 37319cca1b..7f7776e9c0 100644
--- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
+++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb
@@ -2,9 +2,11 @@ require 'action_view/helpers/javascript_helper'
 require 'active_support/json'
 
 module ActionView
+  # = Action View Scriptaculous Helpers
   module Helpers
-    # Provides a set of helpers for calling Scriptaculous JavaScript
-    # functions, including those which create Ajax controls and visual effects.
+    # Provides a set of helpers for calling Scriptaculous[http://script.aculo.us/] 
+    # JavaScript functions, including those which create Ajax controls and visual
+    # effects.
     #
     # To be able to use these helpers, you must include the Prototype
     # JavaScript framework and the Scriptaculous JavaScript library in your
@@ -12,6 +14,7 @@ module ActionView
     # for more information on including the necessary JavaScript.
     #
     # The Scriptaculous helpers' behavior can be tweaked with various options.
+    #
     # See the documentation at http://script.aculo.us for more information on
     # using these helpers in your application.
     module ScriptaculousHelper
diff --git a/actionpack/lib/action_view/helpers/tag_helper.rb b/actionpack/lib/action_view/helpers/tag_helper.rb
index 66277f79fe..d4e8b3d587 100644
--- a/actionpack/lib/action_view/helpers/tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/tag_helper.rb
@@ -2,6 +2,7 @@ require 'active_support/core_ext/object/blank'
 require 'set'
 
 module ActionView
+  # = Action View Tag Helpers
   module Helpers #:nodoc:
     # Provides methods to generate HTML tags programmatically when you can't use
     # a Builder. By default, they output XHTML compliant tags.
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index ccc9156777..9afa989453 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -3,6 +3,7 @@ require 'active_support/core_ext/string/filters'
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Text Helpers
   module Helpers #:nodoc:
     # The TextHelper module provides a set of methods for filtering, formatting
     # and transforming strings, which can reduce the amount of inline Ruby code in
diff --git a/actionpack/lib/action_view/helpers/translation_helper.rb b/actionpack/lib/action_view/helpers/translation_helper.rb
index 0c8829b0b8..dac9c28ab7 100644
--- a/actionpack/lib/action_view/helpers/translation_helper.rb
+++ b/actionpack/lib/action_view/helpers/translation_helper.rb
@@ -1,21 +1,28 @@
 require 'action_view/helpers/tag_helper'
 
 module ActionView
+  # = Action View Translation Helpers
   module Helpers
     module TranslationHelper
-      # Delegates to I18n#translate but also performs three additional functions. First, it'll catch MissingTranslationData exceptions
-      # and turn them into inline spans that contains the missing key, such that you can see in a view what is missing where.
+      # Delegates to I18n#translate but also performs three additional functions.
+      # First, it'll catch MissingTranslationData exceptions and turn them into 
+      # inline spans that contains the missing key, such that you can see in a 
+      # view what is missing where.
       #
-      # Second, it'll scope the key by the current partial if the key starts with a period. So if you call translate(".foo") from the
-      # people/index.html.erb template, you'll actually be calling I18n.translate("people.index.foo"). This makes it less repetitive
-      # to translate many keys within the same partials and gives you a simple framework for scoping them consistently. If you don't
-      # prepend the key with a period, nothing is converted.
+      # Second, it'll scope the key by the current partial if the key starts 
+      # with a period. So if you call <tt>translate(".foo")</tt> from the 
+      # <tt>people/index.html.erb</tt> template, you'll actually be calling 
+      # <tt>I18n.translate("people.index.foo")</tt>. This makes it less repetitive
+      # to translate many keys within the same partials and gives you a simple framework
+      # for scoping them consistently. If you don't prepend the key with a period, 
+      # nothing is converted.
       #
-      # Third, it'll mark the translation as safe HTML if the key has the suffix "_html" or the last element of the key is the word
-      # "html". For example, calling translate("footer_html") or translate("footer.html") will return a safe HTML string that won't
-      # be escaped by other HTML helper methods. This naming convention helps to identify translations that include HTML tags so that
+      # Third, it'll mark the translation as safe HTML if the key has the suffix 
+      # "_html" or the last element of the key is the word "html". For example, 
+      # calling translate("footer_html") or translate("footer.html") will return 
+      # a safe HTML string that won't be escaped by other HTML helper methods. This
+      # naming convention helps to identify translations that include HTML tags so that
       # you know what kind of output to expect when you call translate in a template.
-
       def translate(key, options = {})
         translation = I18n.translate(scope_key_by_partial(key), options.merge!(:raise => true))
         if html_safe_translation_key?(key) && translation.respond_to?(:html_safe)
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 210f148c02..bcfa6a68d7 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -4,6 +4,7 @@ require 'active_support/core_ext/hash/keys'
 require 'action_dispatch'
 
 module ActionView
+  # = Action View URL Helpers
   module Helpers #:nodoc:
     # Provides a set of methods for making links and getting URLs that
     # depend on the routing subsystem (see ActionDispatch::Routing).