Merge pull request #8452 from claudiob/explain_where_chain_parameters

Document the types of arguments accepted by AR#not

2 files changed, 23 insertions, 2 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index d3a13c8e2f..9484092430 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -14,6 +14,15 @@ module ActiveRecord
       # Returns a new relation expressing WHERE + NOT condition
       # according to the conditions in the arguments.
       #
+      # #not accepts conditions in one of these formats: String, Array, Hash.
+      # See #where for more details on each format.
+      #
+      #    User.where.not("name = 'Jon'")
+      #    # SELECT * FROM users WHERE name <> 'Jon'
+      #
+      #    User.where.not(["name = ?", "Jon"])
+      #    # SELECT * FROM users WHERE name <> 'Jon'
+      #
       #    User.where.not(name: "Jon")
       #    # SELECT * FROM users WHERE name <> 'Jon'
       #
@@ -40,7 +49,7 @@ module ActiveRecord
       end
 
       # Returns a new relation expressing WHERE + LIKE condition
-      # according to the conditions in the arguments.
+      # according to the conditions provided as a hash in the arguments.
       #
       #    Book.where.like(title: "Rails%")
       #    # SELECT * FROM books WHERE title LIKE 'Rails%'
@@ -53,7 +62,7 @@ module ActiveRecord
       end
 
       # Returns a new relation expressing WHERE + NOT LIKE condition
-      # according to the conditions in the arguments.
+      # according to the conditions provided as a hash in the arguments.
       #
       #    Conference.where.not_like(name: "%Kaigi")
       #    # SELECT * FROM conferences WHERE name NOT LIKE '%Kaigi'
diff --git a/activerecord/test/cases/relation/where_chain_test.rb b/activerecord/test/cases/relation/where_chain_test.rb
index 8409fc6571..edb3ea48b9 100644
--- a/activerecord/test/cases/relation/where_chain_test.rb
+++ b/activerecord/test/cases/relation/where_chain_test.rb
@@ -50,6 +50,18 @@ module ActiveRecord
       assert_equal(expected, relation.where_values.last)
     end
 
+    def test_not_eq_with_string_parameter
+      expected = Arel::Nodes::Not.new("title = 'hello'")
+      relation = Post.where.not("title = 'hello'")
+      assert_equal([expected], relation.where_values)
+    end
+
+    def test_not_eq_with_array_parameter
+      expected = Arel::Nodes::Not.new("title = 'hello'")
+      relation = Post.where.not(['title = ?', 'hello'])
+      assert_equal([expected], relation.where_values)
+    end
+
     def test_like
       expected = Arel::Nodes::Matches.new(Post.arel_table[:title], 'a%')
       relation = Post.where.like(title: 'a%')