Improve doc for ActiveRecord::Base.unscoped.

1 files changed, 8 insertions, 6 deletions

diff --git a/activerecord/lib/active_record/scoping/default.rb b/activerecord/lib/active_record/scoping/default.rb
index 9840cbccae..6b5070808a 100644
--- a/activerecord/lib/active_record/scoping/default.rb
+++ b/activerecord/lib/active_record/scoping/default.rb
@@ -12,7 +12,7 @@ module ActiveRecord
       end
 
       module ClassMethods
-        # Returns a scope for this class without taking into account the default_scope.
+        # Returns a scope for the model without the default_scope.
         #
         #   class Post < ActiveRecord::Base
         #     def self.default_scope
@@ -23,18 +23,20 @@ module ActiveRecord
         #   Post.all          # Fires "SELECT * FROM posts WHERE published = true"
         #   Post.unscoped.all # Fires "SELECT * FROM posts"
         #
-        # This method also accepts a block meaning that all queries inside the block will
+        # This method also accepts a block. All queries inside the block will
         # not use the default_scope:
         #
         #   Post.unscoped {
         #     Post.limit(10) # Fires "SELECT * FROM posts LIMIT 10"
         #   }
         #
-        # It is recommended to use block form of unscoped because chaining unscoped with <tt>scope</tt>
-        # does not work. Assuming that <tt>published</tt> is a <tt>scope</tt> following two statements are same.
+        # It is recommended to use the block form of unscoped because chaining
+        # unscoped with <tt>scope</tt> does not work.  Assuming that
+        # <tt>published</tt> is a <tt>scope</tt>, the following two statements
+        # are equal: the default_scope is applied on both.
         #
-        # Post.unscoped.published
-        # Post.published
+        #   Post.unscoped.published
+        #   Post.published
         def unscoped #:nodoc:
           block_given? ? relation.scoping { yield } : relation
         end