From c634cb5ece8da75c27832737638c447987a6750c Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Tue, 9 Mar 2021 11:19:38 +0100
Subject: [PATCH] [jOOQ/jOOQ#11591] Misleading Javadoc about
 Settings.isInsertUnchangedRecords

---
 jOOQ/src/main/java/org/jooq/TableRecord.java  | 15 +++++-----
 .../main/java/org/jooq/UpdatableRecord.java   | 28 +++++++++----------
 2 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/jOOQ/src/main/java/org/jooq/TableRecord.java b/jOOQ/src/main/java/org/jooq/TableRecord.java
index 0e3ddc5ec8..4a2efe6a80 100644
--- a/jOOQ/src/main/java/org/jooq/TableRecord.java
+++ b/jOOQ/src/main/java/org/jooq/TableRecord.java
@@ -64,17 +64,16 @@ public interface TableRecord<R extends TableRecord<R>> extends Record {
     R original();
 
     /**
-     * Store this record to the database using an <code>INSERT</code>
-     * statement.
+     * Store this record to the database using an <code>INSERT</code> statement.
      * <p>
-     * If you want to enforce statement execution, regardless if the values in
-     * this record were changed, you can explicitly set the changed flags for
-     * all values with {@link #changed(boolean)} or for single values with
-     * {@link #changed(Field, boolean)}, prior to insertion, or alternatively,
-     * use {@link Settings#isInsertUnchangedRecords()}.
+     * If you want to enforce re-insertion this record's values, regardless if
+     * the values in this record were changed, you can explicitly set the
+     * changed flags for all values with {@link #changed(boolean)} or for single
+     * values with {@link #changed(Field, boolean)}, prior to insertion.
      *
      * @return <code>1</code> if the record was stored to the database. <code>0
-     *         </code> if storing was not necessary.
+     *         </code> if storing was not necessary and
+     *         {@link Settings#isInsertUnchangedRecords()} is set to false.
      * @throws DataAccessException if something went wrong executing the query
      */
     @Support
diff --git a/jOOQ/src/main/java/org/jooq/UpdatableRecord.java b/jOOQ/src/main/java/org/jooq/UpdatableRecord.java
index b9c789ac0e..74908797d4 100644
--- a/jOOQ/src/main/java/org/jooq/UpdatableRecord.java
+++ b/jOOQ/src/main/java/org/jooq/UpdatableRecord.java
@@ -226,12 +226,14 @@ public interface UpdatableRecord<R extends UpdatableRecord<R>> extends TableReco
      * <p>
      * <h3>Statement execution enforcement</h3>
      * <p>
-     * If you want to enforce statement execution, regardless if the values in
-     * this record were changed, you can explicitly set the changed flags for
+     * If you want to control statement re-execution, regardless if the values
+     * in this record were changed, you can explicitly set the changed flags for
      * all values with {@link #changed(boolean)} or for single values with
-     * {@link #changed(Field, boolean)}, prior to storing, or alternatively, use
-     * {@link Settings#getUpdateUnchangedRecords()} and/or
-     * {@link Settings#isInsertUnchangedRecords()}.
+     * {@link #changed(Field, boolean)}, prior to storing. Consider also setting
+     * the flags {@link Settings#getUpdateUnchangedRecords()} and/or
+     * {@link Settings#isInsertUnchangedRecords()} appropriately to control if
+     * the record should be "touched" without any changes (<code>UPDATE</code>)
+     * or inserted with default values (<code>INSERT</code>).
      * <p>
      * This is the same as calling <code>record.store(record.fields())</code>
      *
@@ -283,16 +285,16 @@ public interface UpdatableRecord<R extends UpdatableRecord<R>> extends TableReco
      * This is the same as {@link #store()}, except that an <code>INSERT</code>
      * statement (or no statement) will always be executed.
      * <p>
-     * If you want to enforce statement execution, regardless if the values in
-     * this record were changed, you can explicitly set the changed flags for
-     * all values with {@link #changed(boolean)} or for single values with
-     * {@link #changed(Field, boolean)}, prior to insertion, or alternatively,
-     * use {@link Settings#isInsertUnchangedRecords()}.
+     * If you want to enforce re-insertion this record's values, regardless if
+     * the values in this record were changed, you can explicitly set the
+     * changed flags for all values with {@link #changed(boolean)} or for single
+     * values with {@link #changed(Field, boolean)}, prior to insertion.
      * <p>
      * This is the same as calling <code>record.insert(record.fields())</code>
      *
      * @return <code>1</code> if the record was stored to the database. <code>0
-     *         </code> if storing was not necessary.
+     *         </code> if storing was not necessary and
+     *         {@link Settings#isInsertUnchangedRecords()} is set to false.
      * @throws DataAccessException if something went wrong executing the query
      * @see #store()
      */
@@ -397,9 +399,7 @@ public interface UpdatableRecord<R extends UpdatableRecord<R>> extends TableReco
      * If you want to enforce statement execution, regardless if the values in
      * this record were changed, you can explicitly set the changed flags for
      * all values with {@link #changed(boolean)} or for single values with
-     * {@link #changed(Field, boolean)}, prior to insertion, or alternatively,
-     * use {@link Settings#getUpdateUnchangedRecords()} and/or
-     * {@link Settings#isInsertUnchangedRecords()}..
+     * {@link #changed(Field, boolean)}, prior to insertion.
      * <p>
      * This is the same as calling <code>record.merge(record.fields())</code>
      *