From e2a4224352fa326c045c668850279f5b25e11530 Mon Sep 17 00:00:00 2001 From: Tommaso Visconti Date: Thu, 8 Oct 2015 10:29:05 +0200 Subject: Modify the scope method documentation Adds a paragraph to the documentation of the `ActiveRecord::Scoping::Named.scope` method, explaining that the method is intended to return an ActiveRecord::Relation object to be composable with other scopes. In the case that in the case that `nil` or `false` are returned, the method returns an `all` relation instead. This unexpected behaviour is mentioned in #19249 #14256 #21465 and #21882 and wasn't documented at all. This commit adds this documentation. --- activerecord/lib/active_record/scoping/named.rb | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/scoping/named.rb b/activerecord/lib/active_record/scoping/named.rb index 7b62626896..b2f25752d3 100644 --- a/activerecord/lib/active_record/scoping/named.rb +++ b/activerecord/lib/active_record/scoping/named.rb @@ -39,8 +39,12 @@ module ActiveRecord end end - # Adds a class method for retrieving and querying objects. A \scope - # represents a narrowing of a database query, such as + # Adds a class method for retrieving and querying objects. + # The method is intended to return an ActiveRecord::Relation + # object, which is composable with other scopes. + # If it returns +nil+ or +false+, an all scope is returned instead. + # + # A \scope represents a narrowing of a database query, such as # where(color: :red).select('shirts.*').includes(:washing_instructions). # # class Shirt < ActiveRecord::Base @@ -66,7 +70,8 @@ module ActiveRecord # end # # Unlike Shirt.find(...), however, the object returned by - # Shirt.red is not an Array; it resembles the association object + # Shirt.red is not an Array but an ActiveRecord::Relation, + # which is composable with other scopes; it resembles the association object # constructed by a +has_many+ declaration. For instance, you can invoke # Shirt.red.first, Shirt.red.count, # Shirt.red.where(size: 'small'). Also, just as with the -- cgit v1.2.3