From 315e8952dfbaecd4d5175ea4d0fd95611cad9e01 Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Wed, 2 Jun 2010 01:34:39 +0200
Subject: [PATCH] revises the documentation of String#truncate and the truncate
 helper

---
 .../lib/action_view/helpers/text_helper.rb    | 18 +++++++--------
 .../active_support/core_ext/string/filters.rb | 22 ++++++++-----------
 2 files changed, 18 insertions(+), 22 deletions(-)

diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index 860c1de6af..bfad9f8d31 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -43,25 +43,25 @@ module ActionView
       # ==== 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?
diff --git a/activesupport/lib/active_support/core_ext/string/filters.rb b/activesupport/lib/active_support/core_ext/string/filters.rb
index cdd86a836f..e15a1df9c9 100644
--- a/activesupport/lib/active_support/core_ext/string/filters.rb
+++ b/activesupport/lib/active_support/core_ext/string/filters.rb
@@ -20,25 +20,21 @@ class String
     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] ||= "..."