Clarify the role of `ActiveRecord::Core.encode_with`

Fixes #19568

1 files changed, 8 insertions, 4 deletions

diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb
index 09d7ac374a..9b7cba08de 100644
--- a/activerecord/lib/active_record/core.rb
+++ b/activerecord/lib/active_record/core.rb
@@ -305,15 +305,19 @@ module ActiveRecord
       _run_initialize_callbacks
     end
 
-    # Initialize an empty model object from +coder+. +coder+ must contain
-    # the attributes necessary for initializing an empty model object. For
-    # example:
+    # Initialize an empty model object from +coder+. +coder+ should be
+    # the result of previously encoding an Active Record model, using
+    # `encode_with`
     #
     #   class Post < ActiveRecord::Base
     #   end
     #
+    #   old_post = Post.new(title: "hello world")
+    #   coder = {}
+    #   old_post.encode_with(coder)
+    #
     #   post = Post.allocate
-    #   post.init_with('attributes' => { 'title' => 'hello world' })
+    #   post.init_with(coder)
     #   post.title # => 'hello world'
     def init_with(coder)
       coder = LegacyYamlAdapter.convert(self.class, coder)