revises the documentation of String#truncate and the truncate helper

Author: fxn

actionpack/lib/action_view/helpers/text_helper.rb

@@ -43,25 +43,25 @@ def safe_concat(string)
       # ==== Examples
       #
       #   truncate("Once upon a time in a world far far away")
-      #   # => Once upon a time in a worl...
+      #   # => "Once upon a time in a world..."
       #
-      #   truncate("Once upon a time in a world far far away", :separator => ' ')
-      #   # => Once upon a time in a world...
+      #   truncate("Once upon a time in a world far far away", :length => 17)
+      #   # => "Once upon a ti..."
       #
-      #   truncate("Once upon a time in a world far far away", :length => 14)
-      #   # => Once upon a...
+      #   truncate("Once upon a time in a world far far away", :lenght => 17, :separator => ' ')
+      #   # => "Once upon a..."
       #
-      #   truncate("And they found that many people were sleeping better.", :omission => "... (continued)", :length => 25)
-      #   # => And they f... (continued)
+      #   truncate("And they found that many people were sleeping better.", :length => 25, :omission => '... (continued)')
+      #   # => "And they f... (continued)"
       #
       # You can still use <tt>truncate</tt> with the old API that accepts the
       # +length+ as its optional second and the +ellipsis+ as its
       # optional third parameter:
       #   truncate("Once upon a time in a world far far away", 14)
-      #   # => Once upon a...
+      #   # => "Once upon a..."
       #
       #   truncate("And they found that many people were sleeping better.", 25, "... (continued)")
-      #   # => And they f... (continued)
+      #   # => "And they f... (continued)"
       def truncate(text, *args)
         options = args.extract_options!
         unless args.empty?

activesupport/lib/active_support/core_ext/string/filters.rb

@@ -20,25 +20,21 @@ def squish!
     self
   end
 
-  # Truncates a given +text+ after a given <tt>length</tt> if +text+ is longer than <tt>length</tt>.
-  # The last characters will be replaced with the <tt>:omission</tt> (defaults to "...")
-  # for a total length not exceeding <tt>:length</tt>.
+  # Truncates a given +text+ after a given <tt>length</tt> if +text+ is longer than <tt>length</tt>:
   #
-  # Pass a <tt>:separator</tt> to truncate +text+ at a natural break.
+  #   "Once upon a time in a world far far away".truncate(27)
+  #   # => "Once upon a time in a wo..."
   #
-  # ==== Examples
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
+  # for a total length not exceeding <tt>:length</tt>:
   #
-  #   "Once upon a time in a world far far away".truncate(30)
-  #   # => Once upon a time in a worl...
+  #   "Once upon a time in a world far far away".truncate(27, :separator => ' ')
+  #   # => "Once upon a time in a..."
   #
-  #   "Once upon a time in a world far far away".truncate(30, :separator => ' ')
-  #   # => Once upon a time in a world...
-  #
-  #   "Once upon a time in a world far far away".truncate(14)
-  #   # => Once upon a...
+  # Pass a <tt>:separator</tt> to truncate +text+ at a natural break:
   #
   #   "And they found that many people were sleeping better.".truncate(25, :omission => "... (continued)")
-  #   # => And they f... (continued)
+  #   # => "And they f... (continued)"
   def truncate(length, options = {})
     text = self.dup
     options[:omission] ||= "..."