diff options
| author | Tommaso Visconti <tommaso.visconti@gmail.com> | 2015-10-08 10:29:05 +0200 |
|---|---|---|
| committer | Tommaso Visconti <tommaso.visconti@gmail.com> | 2015-10-08 10:29:05 +0200 |
| commit | e2a4224352fa326c045c668850279f5b25e11530 (patch) | |
| tree | 601e137fedd20cbde1b6f2324ca1c5208755bb88 /activerecord/lib | |
| parent | eaa0cb7924d5ffd0de04492a7198e0d79088aaae (diff) | |
| download | rails-e2a4224352fa326c045c668850279f5b25e11530.tar.gz rails-e2a4224352fa326c045c668850279f5b25e11530.tar.bz2 rails-e2a4224352fa326c045c668850279f5b25e11530.zip | |
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.
Diffstat (limited to 'activerecord/lib')
| -rw-r--r-- | activerecord/lib/active_record/scoping/named.rb | 11 |
1 files changed, 8 insertions, 3 deletions
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 <tt>ActiveRecord::Relation</tt> + # object, which is composable with other scopes. + # If it returns +nil+ or +false+, an <tt>all</tt> scope is returned instead. + # + # A \scope represents a narrowing of a database query, such as # <tt>where(color: :red).select('shirts.*').includes(:washing_instructions)</tt>. # # class Shirt < ActiveRecord::Base @@ -66,7 +70,8 @@ module ActiveRecord # end # # Unlike <tt>Shirt.find(...)</tt>, however, the object returned by - # <tt>Shirt.red</tt> is not an Array; it resembles the association object + # <tt>Shirt.red</tt> is not an Array but an <tt>ActiveRecord::Relation</tt>, + # which is composable with other scopes; it resembles the association object # constructed by a +has_many+ declaration. For instance, you can invoke # <tt>Shirt.red.first</tt>, <tt>Shirt.red.count</tt>, # <tt>Shirt.red.where(size: 'small')</tt>. Also, just as with the |