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