diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index d8a6d7feb9e7e..620071c056ef5 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -456,7 +456,7 @@ def update!(id = :all, attributes)
       end
 
       # Accepts a list of attribute names to be used in the WHERE clause
-      # of SELECT / UPDATE / DELETE queries and in the ORDER BY clause for `#first` and `#last` finder methods.
+      # of SELECT / UPDATE / DELETE queries and in the ORDER BY clause for +#first+ and +#last+ finder methods.
       #
       #   class Developer < ActiveRecord::Base
       #     query_constraints :company_id, :id
@@ -469,7 +469,7 @@ def update!(id = :all, attributes)
       #   developer.update!(name: "Nikita")
       #   # UPDATE "developers" SET "name" = 'Nikita' WHERE "developers"."company_id" = 1 AND "developers"."id" = 1
       #
-      #   It is possible to update attribute used in the query_by clause:
+      #   # It is possible to update attribute used in the query_constraints clause:
       #   developer.update!(company_id: 2)
       #   # UPDATE "developers" SET "company_id" = 2 WHERE "developers"."company_id" = 1 AND "developers"."id" = 1
       #