document the AR none method [ci skip]

2 files changed, 31 insertions, 7 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 6a28d7b155..b6d762c2e2 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -201,26 +201,26 @@ module ActiveRecord
     #
     # The returned NullRelation inherits from Relation and implements the
     # Null Object pattern so it is an object with defined null behavior:
-    # it always returns an empty array of records and avoids any database query.
+    # it always returns an empty array of records and does not query the database.
     #
     # Any subsequent condition chained to the returned relation will continue
     # generating an empty relation and will not fire any query to the database.
     #
-    # Used in cases where is needed a method or a scope that could return zero
-    # results but the response has to be chainable.
+    # This is useful in scenarios where you need a chainable response to a method
+    # or a scope that could return zero results.
     #
     # For example:
     #
     #   @posts = current_user.visible_posts.where(:name => params[:name])
-    #   # => the visible_post method response has to be a chainable Relation
+    #   # => the visible_posts method is expected to return a chainable Relation
     #
     #   def visible_posts
     #     case role
-    #     if 'Country Manager'
+    #     when 'Country Manager'
     #       Post.where(:country => country)
-    #     if 'Reviewer'
+    #     when 'Reviewer'
     #       Post.published
-    #     if 'Bad User'
+    #     when 'Bad User'
     #       Post.none # => returning [] instead breaks the previous code
     #     end
     #   end
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index 3b4f2befda..21bbc64255 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -608,6 +608,30 @@ SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
 
 This method accepts *no* arguments.
 
+h3. Null Relation
+
+The +none+ method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results.
+
+<ruby>
+Post.none # returns an empty Relation and fires no queries.
+</ruby>
+
+<ruby>
+# The visible_posts method below is expected to return a Relation.
+@posts = current_user.visible_posts.where(:name => params[:name])
+
+def visible_posts
+  case role
+  when 'Country Manager'
+    Post.where(:country => country)
+  when 'Reviewer'
+    Post.published
+  when 'Bad User'
+    Post.none # => returning [] or nil breaks the caller code in this case
+  end
+end
+</ruby>
+
 h3. Readonly Objects
 
 Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.