diff --git a/activerecord/lib/active_record/scoping/named.rb b/activerecord/lib/active_record/scoping/named.rb index 7b626268962340e02a5a4eecf9f53f0017418dea..b2f25752d37c06628ff50739839d4dc2758ab053 100644 --- a/activerecord/lib/active_record/scoping/named.rb +++ b/activerecord/lib/active_record/scoping/named.rb @@ -39,8 +39,12 @@ def default_scoped # :nodoc: 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 @@ def default_scoped # :nodoc: # 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