AS guide: 2nd revision of the explanation of to_param

1 files changed, 9 insertions, 3 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 4b8be1f9eb..d45aff81a0 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -98,7 +98,7 @@ Rails has classes that act like +Date+ or +Time+ and follow this contract.
 
 h4. +to_param+
 
-All objects in Rails respond to the method +to_param+, which is meant to return a value that represents them as value in a query string, or as a URL fragment.
+All objects in Rails respond to the method +to_param+, which is meant to return something that represents them as values in a query string, or as a URL fragments.
 
 By default +to_param+ just calls +to_s+:
 
@@ -106,7 +106,13 @@ By default +to_param+ just calls +to_s+:
 7.to_param # => "7"
 </ruby>
 
-and some classes in Rails overwrite it.
+The return value of +to_param+ should *not* be escaped:
+
+<ruby>
+"Tom & Jerry".to_param # => "Tom & Jerry"
+</ruby>
+
+Several classes in Rails overwrite these method.
 
 For example +nil+, +true+, and +false+ return themselves. +Array#to_param+ calls +to_param+ on the elements and joins the result with "/":
 
@@ -124,7 +130,7 @@ class User
 end
 </ruby>
 
-you get:
+we get:
 
 <ruby>
 user_path(@user) # => "/users/357-john-smith"