nodoc the first_or_create methods and document alternatives

3 files changed, 39 insertions, 40 deletions

diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md
index 1edcd7cfc8..ed5d0eebdf 100644
--- a/activerecord/CHANGELOG.md
+++ b/activerecord/CHANGELOG.md
@@ -24,9 +24,17 @@
     Which obviously does not affect the scoping of queries within
     callbacks.
 
-    The `find_or_create_by` version also reads better, frankly. But note
-    that it does not allow attributes to be specified for the `create`
-    that are not included in the `find_by`.
+    The `find_or_create_by` version also reads better, frankly.
+
+    If you need to add extra attributes during create, you can do one of:
+
+        User.create_with(active: true).find_or_create_by(first_name: 'Jon')
+        User.find_or_create_by(first_name: 'Jon') { |u| u.active = true }
+
+    The `first_or_create` family of methods have been nodoc'ed in favour
+    of this API. They may be deprecated in the future but their
+    implementation is very small and it's probably not worth putting users
+    through lots of annoying deprecation warnings.
 
     *Jon Leighton*
 
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index d106fceca2..2e2286e4fd 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -129,60 +129,41 @@ module ActiveRecord
       scoping { @klass.create!(*args, &block) }
     end
 
-    # Tries to load the first record; if it fails, then <tt>create</tt> is called with the same arguments as this method.
-    #
-    # Expects arguments in the same format as +Base.create+.
-    #
-    # Note that the <tt>create</tt> will execute within the context of this scope, and that may for example
-    # affect the result of queries within callbacks. If you don't want this, use the <tt>find_or_create_by</tt>
-    # method.
+    def first_or_create(attributes = nil, &block) # :nodoc:
+      first || create(attributes, &block)
+    end
+
+    def first_or_create!(attributes = nil, &block) # :nodoc:
+      first || create!(attributes, &block)
+    end
+
+    def first_or_initialize(attributes = nil, &block) # :nodoc:
+      first || new(attributes, &block)
+    end
+
+    # Finds the first record with the given attributes, or creates a record with the attributes
+    # if one is not found.
     #
     # ==== Examples
     #   # Find the first user named Penélope or create a new one.
-    #   User.where(:first_name => 'Penélope').first_or_create
+    #   User.find_or_create_by(first_name: 'Penélope')
     #   # => <User id: 1, first_name: 'Penélope', last_name: nil>
     #
     #   # Find the first user named Penélope or create a new one.
     #   # We already have one so the existing record will be returned.
-    #   User.where(:first_name => 'Penélope').first_or_create
+    #   User.find_or_create_by(first_name: 'Penélope')
     #   # => <User id: 1, first_name: 'Penélope', last_name: nil>
     #
     #   # Find the first user named Scarlett or create a new one with a particular last name.
-    #   User.where(:first_name => 'Scarlett').first_or_create(:last_name => 'Johansson')
+    #   User.create_with(last_name: 'Johansson').find_or_create_by(first_name: 'Scarlett')
     #   # => <User id: 2, first_name: 'Scarlett', last_name: 'Johansson'>
     #
     #   # Find the first user named Scarlett or create a new one with a different last name.
     #   # We already have one so the existing record will be returned.
-    #   User.where(:first_name => 'Scarlett').first_or_create do |user|
+    #   User.find_or_create_by(first_name: 'Scarlett') do |user|
     #     user.last_name = "O'Hara"
     #   end
     #   # => <User id: 2, first_name: 'Scarlett', last_name: 'Johansson'>
-    def first_or_create(attributes = nil, &block)
-      first || create(attributes, &block)
-    end
-
-    # Like <tt>first_or_create</tt> but calls <tt>create!</tt> so an exception is raised if the created record is invalid.
-    #
-    # Expects arguments in the same format as <tt>Base.create!</tt>.
-    def first_or_create!(attributes = nil, &block)
-      first || create!(attributes, &block)
-    end
-
-    # Like <tt>first_or_create</tt> but calls <tt>new</tt> instead of <tt>create</tt>.
-    #
-    # Expects arguments in the same format as <tt>Base.new</tt>.
-    def first_or_initialize(attributes = nil, &block)
-      first || new(attributes, &block)
-    end
-
-    # Finds the first record with the given attributes, or creates it if one does not exist.
-    #
-    # See also <tt>first_or_create</tt>.
-    #
-    # ==== Examples
-    #   # Find the first user named Penélope or create a new one.
-    #   User.find_or_create_by(first_name: 'Penélope')
-    #   # => <User id: 1, first_name: 'Penélope', last_name: nil>
     def find_or_create_by(attributes, &block)
       find_by(attributes) || create(attributes, &block)
     end
diff --git a/activerecord/test/cases/relations_test.rb b/activerecord/test/cases/relations_test.rb
index 7504da01d5..5f96145b47 100644
--- a/activerecord/test/cases/relations_test.rb
+++ b/activerecord/test/cases/relations_test.rb
@@ -1067,6 +1067,16 @@ class RelationTest < ActiveRecord::TestCase
     assert_equal bird, Bird.find_or_create_by(name: 'bob')
   end
 
+  def test_find_or_create_by_with_create_with
+    assert_nil Bird.find_by(name: 'bob')
+
+    bird = Bird.create_with(color: 'green').find_or_create_by(name: 'bob')
+    assert bird.persisted?
+    assert_equal 'green', bird.color
+
+    assert_equal bird, Bird.create_with(color: 'blue').find_or_create_by(name: 'bob')
+  end
+
   def test_find_or_create_by!
     assert_raises(ActiveRecord::RecordInvalid) { Bird.find_or_create_by!(color: 'green') }
   end