Cleans documentation from Helpers [ci skip]

5 files changed, 98 insertions, 121 deletions

diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb
index 6e51ba66a5..1fbf61a5a9 100644
--- a/actionpack/lib/action_view/helpers/date_helper.rb
+++ b/actionpack/lib/action_view/helpers/date_helper.rb
@@ -45,7 +45,6 @@ module ActionView
       #   40-59 secs      # => less than a minute
       #   60-89 secs      # => 1 minute
       #
-      # ==== Examples
       #   from_time = Time.now
       #   distance_of_time_in_words(from_time, from_time + 50.minutes)                                # => about 1 hour
       #   distance_of_time_in_words(from_time, 50.minutes.from_now)                                   # => about 1 hour
@@ -166,7 +165,6 @@ 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+).
       #
-      #
       # ==== Options
       # * <tt>:use_month_numbers</tt> - Set to true if you want to use month numbers rather than month names (e.g.
       #   "2" instead of "February").
diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index c79d30ea88..390c9705d8 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -105,11 +105,12 @@ module ActionView
     #
     #   if @person.update_attributes(params[:person])
     #     # success
-    #   else
+    #   els
     #     # error handling
     #   end
     #
-    # That's how you typically work with resources.
+    # That's how you typically work with resources. Note that it
+    # would probably improve by using the Strong Parameters functionality
     module FormHelper
       extend ActiveSupport::Concern
 
diff --git a/actionpack/lib/action_view/helpers/javascript_helper.rb b/actionpack/lib/action_view/helpers/javascript_helper.rb
index 1a99fc7091..cfdd7c77d8 100644
--- a/actionpack/lib/action_view/helpers/javascript_helper.rb
+++ b/actionpack/lib/action_view/helpers/javascript_helper.rb
@@ -18,7 +18,8 @@ module ActionView
 
       # Escapes carriage returns and single and double quotes for JavaScript segments.
       #
-      # Also available through the alias j(). This is particularly helpful in JavaScript responses, like:
+      # Also available through the alias j(). This is particularly helpful in JavaScript
+      # responses, like:
       #
       #   $('some_element').replaceWith('<%=j render 'some/element_template' %>');
       def escape_javascript(javascript)
@@ -43,12 +44,14 @@ module ActionView
       #   </script>
       #
       # +html_options+ may be a hash of attributes for the <tt>\<script></tt>
-      # tag. Example:
+      # tag.
+      #
       #   javascript_tag "alert('All is good')", defer: 'defer'
       #   # => <script defer="defer">alert('All is good')</script>
       #
       # Instead of passing the content as an argument, you can also use a block
       # in which case, you pass your +html_options+ as the first parameter.
+      #
       #   <%= javascript_tag defer: 'defer' do -%>
       #     alert('All is good')
       #   <% end -%>
diff --git a/actionpack/lib/action_view/helpers/number_helper.rb b/actionpack/lib/action_view/helpers/number_helper.rb
index 82340171af..96ab47a0a3 100644
--- a/actionpack/lib/action_view/helpers/number_helper.rb
+++ b/actionpack/lib/action_view/helpers/number_helper.rb
@@ -28,8 +28,6 @@ module ActionView
       # Formats a +number+ into a US phone number (e.g., (555)
       # 123-9876). You can customize the format in the +options+ hash.
       #
-      # ==== Options
-      #
       # * <tt>:area_code</tt> - Adds parentheses around the area code.
       # * <tt>:delimiter</tt> - Specifies the delimiter to use
       #   (defaults to "-").
@@ -40,21 +38,18 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_to_phone(5551234)                                           # => 555-1234
-      #  number_to_phone("5551234")                                         # => 555-1234
-      #  number_to_phone(1235551234)                                        # => 123-555-1234
-      #  number_to_phone(1235551234, area_code: true)                    # => (123) 555-1234
-      #  number_to_phone(1235551234, delimiter: " ")                     # => 123 555 1234
-      #  number_to_phone(1235551234, area_code: true, extension: 555) # => (123) 555-1234 x 555
-      #  number_to_phone(1235551234, country_code: 1)                    # => +1-123-555-1234
-      #  number_to_phone("123a456")                                         # => 123a456
-      #
-      #  number_to_phone("1234a567", raise: true)                        # => InvalidNumberError
-      #
-      #  number_to_phone(1235551234, country_code: 1, extension: 1343, delimiter: ".")
-      #  # => +1.123.555.1234 x 1343
+      #   number_to_phone(5551234)                                           # => 555-1234
+      #   number_to_phone("5551234")                                         # => 555-1234
+      #   number_to_phone(1235551234)                                        # => 123-555-1234
+      #   number_to_phone(1235551234, area_code: true)                       # => (123) 555-1234
+      #   number_to_phone(1235551234, delimiter: " ")                        # => 123 555 1234
+      #   number_to_phone(1235551234, area_code: true, extension: 555)       # => (123) 555-1234 x 555
+      #   number_to_phone(1235551234, country_code: 1)                       # => +1-123-555-1234
+      #   number_to_phone("123a456")                                         # => 123a456
+      #   number_to_phone("1234a567", raise: true)                           # => InvalidNumberError
+      #
+      #   number_to_phone(1235551234, country_code: 1, extension: 1343, delimiter: ".")
+      #   # => +1.123.555.1234 x 1343
       def number_to_phone(number, options = {})
         return unless number
         options = options.symbolize_keys
@@ -66,8 +61,6 @@ module ActionView
       # Formats a +number+ into a currency string (e.g., $13.65). You
       # can customize the format in the +options+ hash.
       #
-      # ==== Options
-      #
       # * <tt>:locale</tt> - Sets the locale to be used for formatting
       #   (defaults to current locale).
       # * <tt>:precision</tt> - Sets the level of precision (defaults
@@ -89,22 +82,20 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_to_currency(1234567890.50)                    # => $1,234,567,890.50
-      #  number_to_currency(1234567890.506)                   # => $1,234,567,890.51
-      #  number_to_currency(1234567890.506, precision: 3)  # => $1,234,567,890.506
-      #  number_to_currency(1234567890.506, locale: :fr)   # => 1 234 567 890,51 €
-      #  number_to_currency("123a456")                        # => $123a456
+      #   number_to_currency(1234567890.50)                    # => $1,234,567,890.50
+      #   number_to_currency(1234567890.506)                   # => $1,234,567,890.51
+      #   number_to_currency(1234567890.506, precision: 3)     # => $1,234,567,890.506
+      #   number_to_currency(1234567890.506, locale: :fr)      # => 1 234 567 890,51 €
+      #   number_to_currency("123a456")                        # => $123a456
       #
-      #  number_to_currency("123a456", raise: true)        # => InvalidNumberError
+      #   number_to_currency("123a456", raise: true)        # => InvalidNumberError
       #
-      #  number_to_currency(-1234567890.50, negative_format: "(%u%n)")
-      #  # => ($1,234,567,890.50)
-      #  number_to_currency(1234567890.50, unit: "&pound;", separator: ",", delimiter: "")
-      #  # => &pound;1234567890,50
-      #  number_to_currency(1234567890.50, unit: "&pound;", separator: ",", delimiter: "", format: "%n %u")
-      #  # => 1234567890,50 &pound;
+      #   number_to_currency(-1234567890.50, negative_format: "(%u%n)")
+      #   # => ($1,234,567,890.50)
+      #   number_to_currency(1234567890.50, unit: "&pound;", separator: ",", delimiter: "")
+      #   # => &pound;1234567890,50
+      #   number_to_currency(1234567890.50, unit: "&pound;", separator: ",", delimiter: "", format: "%n %u")
+      #   # => 1234567890,50 &pound;
       def number_to_currency(number, options = {})
         return unless number
         options = escape_unsafe_delimiters_and_separators(options.symbolize_keys)
@@ -117,7 +108,6 @@ module ActionView
       # Formats a +number+ as a percentage string (e.g., 65%). You can
       # customize the format in the +options+ hash.
       #
-      # ==== Options
       #
       # * <tt>:locale</tt> - Sets the locale to be used for formatting
       #   (defaults to current locale).
@@ -138,18 +128,16 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
+      #   number_to_percentage(100)                                        # => 100.000%
+      #   number_to_percentage("98")                                       # => 98.000%
+      #   number_to_percentage(100, precision: 0)                          # => 100%
+      #   number_to_percentage(1000, delimiter: '.', separator: ',')       # => 1.000,000%
+      #   number_to_percentage(302.24398923423, precision: 5)              # => 302.24399%
+      #   number_to_percentage(1000, locale: :fr)                          # => 1 000,000%
+      #   number_to_percentage("98a")                                      # => 98a%
+      #   number_to_percentage(100, format: "%n  %")                       # => 100  %
       #
-      #  number_to_percentage(100)                                        # => 100.000%
-      #  number_to_percentage("98")                                       # => 98.000%
-      #  number_to_percentage(100, precision: 0)                       # => 100%
-      #  number_to_percentage(1000, delimiter: '.', separator: ',') # => 1.000,000%
-      #  number_to_percentage(302.24398923423, precision: 5)           # => 302.24399%
-      #  number_to_percentage(1000, locale: :fr)                       # => 1 000,000%
-      #  number_to_percentage("98a")                                      # => 98a%
-      #  number_to_percentage(100, format: "%n  %")                    # => 100  %
-      #
-      #  number_to_percentage("98a", raise: true)                      # => InvalidNumberError
+      #   number_to_percentage("98a", raise: true)                         # => InvalidNumberError
       def number_to_percentage(number, options = {})
         return unless number
         options = escape_unsafe_delimiters_and_separators(options.symbolize_keys)
@@ -163,8 +151,6 @@ module ActionView
       # (e.g., 12,324). You can customize the format in the +options+
       # hash.
       #
-      # ==== Options
-      #
       # * <tt>:locale</tt> - Sets the locale to be used for formatting
       #   (defaults to current locale).
       # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
@@ -174,20 +160,18 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_with_delimiter(12345678)                        # => 12,345,678
-      #  number_with_delimiter("123456")                        # => 123,456
-      #  number_with_delimiter(12345678.05)                     # => 12,345,678.05
-      #  number_with_delimiter(12345678, delimiter: ".")     # => 12.345.678
-      #  number_with_delimiter(12345678, delimiter: ",")     # => 12,345,678
-      #  number_with_delimiter(12345678.05, separator: " ")  # => 12,345,678 05
-      #  number_with_delimiter(12345678.05, locale: :fr)     # => 12 345 678,05
-      #  number_with_delimiter("112a")                          # => 112a
-      #  number_with_delimiter(98765432.98, delimiter: " ", separator: ",")
-      #  # => 98 765 432,98
-      #
-      #  number_with_delimiter("112a", raise: true)          # => raise InvalidNumberError
+      #   number_with_delimiter(12345678)                        # => 12,345,678
+      #   number_with_delimiter("123456")                        # => 123,456
+      #   number_with_delimiter(12345678.05)                     # => 12,345,678.05
+      #   number_with_delimiter(12345678, delimiter: ".")        # => 12.345.678
+      #   number_with_delimiter(12345678, delimiter: ",")        # => 12,345,678
+      #   number_with_delimiter(12345678.05, separator: " ")     # => 12,345,678 05
+      #   number_with_delimiter(12345678.05, locale: :fr)        # => 12 345 678,05
+      #   number_with_delimiter("112a")                          # => 112a
+      #   number_with_delimiter(98765432.98, delimiter: " ", separator: ",")
+      #   # => 98 765 432,98
+      #
+      #  number_with_delimiter("112a", raise: true)             # => raise InvalidNumberError
       def number_with_delimiter(number, options = {})
         options = escape_unsafe_delimiters_and_separators(options.symbolize_keys)
 
@@ -201,8 +185,6 @@ module ActionView
       # +:significant+ is +false+, and 5 if +:significant+ is +true+).
       # You can customize the format in the +options+ hash.
       #
-      # ==== Options
-      #
       # * <tt>:locale</tt> - Sets the locale to be used for formatting
       #   (defaults to current locale).
       # * <tt>:precision</tt> - Sets the precision of the number
@@ -220,23 +202,21 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_with_precision(111.2345)                                            # => 111.235
-      #  number_with_precision(111.2345, precision: 2)                           # => 111.23
-      #  number_with_precision(13, precision: 5)                                 # => 13.00000
-      #  number_with_precision(389.32314, precision: 0)                          # => 389
-      #  number_with_precision(111.2345, significant: true)                      # => 111
-      #  number_with_precision(111.2345, precision: 1, significant: true)     # => 100
-      #  number_with_precision(13, precision: 5, significant: true)           # => 13.000
-      #  number_with_precision(111.234, locale: :fr)                             # => 111,234
-      #
-      #  number_with_precision(13, precision: 5, significant: true, strip_insignificant_zeros: true)
-      #  # => 13
-      #
-      #  number_with_precision(389.32314, precision: 4, significant: true)    # => 389.3
-      #  number_with_precision(1111.2345, precision: 2, separator: ',', delimiter: '.')
-      #  # => 1.111,23
+      #   number_with_precision(111.2345)                                            # => 111.235
+      #   number_with_precision(111.2345, precision: 2)                           # => 111.23
+      #   number_with_precision(13, precision: 5)                                 # => 13.00000
+      #   number_with_precision(389.32314, precision: 0)                          # => 389
+      #   number_with_precision(111.2345, significant: true)                      # => 111
+      #   number_with_precision(111.2345, precision: 1, significant: true)     # => 100
+      #   number_with_precision(13, precision: 5, significant: true)           # => 13.000
+      #   number_with_precision(111.234, locale: :fr)                             # => 111,234
+      #
+      #   number_with_precision(13, precision: 5, significant: true, strip_insignificant_zeros: true)
+      #   # => 13
+      #
+      #   number_with_precision(389.32314, precision: 4, significant: true)    # => 389.3
+      #   number_with_precision(1111.2345, precision: 2, separator: ',', delimiter: '.')
+      #   # => 1.111,23
       def number_with_precision(number, options = {})
         options = escape_unsafe_delimiters_and_separators(options.symbolize_keys)
 
@@ -245,7 +225,6 @@ module ActionView
         }
       end
 
-
       # Formats the bytes in +number+ into a more understandable
       # representation (e.g., giving it 1500 yields 1.5 KB). This
       # method is useful for reporting file sizes to users. You can
@@ -254,8 +233,6 @@ module ActionView
       # See <tt>number_to_human</tt> if you want to pretty-print a
       # generic number.
       #
-      # ==== Options
-      #
       # * <tt>:locale</tt> - Sets the locale to be used for formatting
       #   (defaults to current locale).
       # * <tt>:precision</tt> - Sets the precision of the number
@@ -275,24 +252,23 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_to_human_size(123)                                          # => 123 Bytes
-      #  number_to_human_size(1234)                                         # => 1.21 KB
-      #  number_to_human_size(12345)                                        # => 12.1 KB
-      #  number_to_human_size(1234567)                                      # => 1.18 MB
-      #  number_to_human_size(1234567890)                                   # => 1.15 GB
-      #  number_to_human_size(1234567890123)                                # => 1.12 TB
-      #  number_to_human_size(1234567, precision: 2)                     # => 1.2 MB
-      #  number_to_human_size(483989, precision: 2)                      # => 470 KB
-      #  number_to_human_size(1234567, precision: 2, separator: ',')  # => 1,2 MB
+      #   number_to_human_size(123)                                          # => 123 Bytes
+      #   number_to_human_size(1234)                                         # => 1.21 KB
+      #   number_to_human_size(12345)                                        # => 12.1 KB
+      #   number_to_human_size(1234567)                                      # => 1.18 MB
+      #   number_to_human_size(1234567890)                                   # => 1.15 GB
+      #   number_to_human_size(1234567890123)                                # => 1.12 TB
+      #   number_to_human_size(1234567, precision: 2)                        # => 1.2 MB
+      #   number_to_human_size(483989, precision: 2)                         # => 470 KB
+      #   number_to_human_size(1234567, precision: 2, separator: ',')        # => 1,2 MB
       #
       # Non-significant zeros after the fractional separator are
       # stripped out by default (set
       # <tt>:strip_insignificant_zeros</tt> to +false+ to change
       # that):
-      #  number_to_human_size(1234567890123, precision: 5)        # => "1.1229 TB"
-      #  number_to_human_size(524288000, precision: 5)            # => "500 MB"
+      #
+      #   number_to_human_size(1234567890123, precision: 5)        # => "1.1229 TB"
+      #   number_to_human_size(524288000, precision: 5)            # => "500 MB"
       def number_to_human_size(number, options = {})
         options = escape_unsafe_delimiters_and_separators(options.symbolize_keys)
 
@@ -348,29 +324,27 @@ module ActionView
       # * <tt>:raise</tt> - If true, raises +InvalidNumberError+ when
       #   the argument is invalid.
       #
-      # ==== Examples
-      #
-      #  number_to_human(123)                                          # => "123"
-      #  number_to_human(1234)                                         # => "1.23 Thousand"
-      #  number_to_human(12345)                                        # => "12.3 Thousand"
-      #  number_to_human(1234567)                                      # => "1.23 Million"
-      #  number_to_human(1234567890)                                   # => "1.23 Billion"
-      #  number_to_human(1234567890123)                                # => "1.23 Trillion"
-      #  number_to_human(1234567890123456)                             # => "1.23 Quadrillion"
-      #  number_to_human(1234567890123456789)                          # => "1230 Quadrillion"
-      #  number_to_human(489939, precision: 2)                      # => "490 Thousand"
-      #  number_to_human(489939, precision: 4)                      # => "489.9 Thousand"
-      #  number_to_human(1234567, precision: 4,
-      #                           significant: false)               # => "1.2346 Million"
-      #  number_to_human(1234567, precision: 1,
+      #   number_to_human(123)                                          # => "123"
+      #   number_to_human(1234)                                         # => "1.23 Thousand"
+      #   number_to_human(12345)                                        # => "12.3 Thousand"
+      #   number_to_human(1234567)                                      # => "1.23 Million"
+      #   number_to_human(1234567890)                                   # => "1.23 Billion"
+      #   number_to_human(1234567890123)                                # => "1.23 Trillion"
+      #   number_to_human(1234567890123456)                             # => "1.23 Quadrillion"
+      #   number_to_human(1234567890123456789)                          # => "1230 Quadrillion"
+      #   number_to_human(489939, precision: 2)                         # => "490 Thousand"
+      #   number_to_human(489939, precision: 4)                         # => "489.9 Thousand"
+      #   number_to_human(1234567, precision: 4,
+      #                           significant: false)                   # => "1.2346 Million"
+      #   number_to_human(1234567, precision: 1,
       #                           separator: ',',
-      #                           significant: false)               # => "1,2 Million"
+      #                           significant: false)                   # => "1,2 Million"
       #
       # Non-significant zeros after the decimal separator are stripped
       # out by default (set <tt>:strip_insignificant_zeros</tt> to
       # +false+ to change that):
-      #  number_to_human(12345012345, significant_digits: 6)       # => "12.345 Billion"
-      #  number_to_human(500000000, precision: 5)                  # => "500 Million"
+      #   number_to_human(12345012345, significant_digits: 6)       # => "12.345 Billion"
+      #   number_to_human(500000000, precision: 5)                  # => "500 Million"
       #
       # ==== Custom Unit Quantifiers
       #
diff --git a/actionpack/lib/action_view/helpers/output_safety_helper.rb b/actionpack/lib/action_view/helpers/output_safety_helper.rb
index 2e7e9dc50c..60a4478c26 100644
--- a/actionpack/lib/action_view/helpers/output_safety_helper.rb
+++ b/actionpack/lib/action_view/helpers/output_safety_helper.rb
@@ -11,7 +11,8 @@ module ActionView #:nodoc:
       #
       # For example:
       #
-      # <%=raw @user.name %>
+      #  raw @user.name
+      #  # => 'Jimmy <alert>Tables</alert>'
       def raw(stringish)
         stringish.to_s.html_safe
       end