From cd1e22844492752cf4ad4aeb206229db30a2b2b2 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Fri, 29 Jun 2012 14:56:49 +0200
Subject: [PATCH] [#1504] Document behaviour of fetch() and fetchOne() in case
 jOOQ cannot fetch actual records

---
 jOOQ/src/main/java/org/jooq/InsertQuery.java      | 15 +++++++++++++--
 jOOQ/src/main/java/org/jooq/InsertResultStep.java | 14 ++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/jOOQ/src/main/java/org/jooq/InsertQuery.java b/jOOQ/src/main/java/org/jooq/InsertQuery.java
index 7cc0a34f47..590d8669d4 100644
--- a/jOOQ/src/main/java/org/jooq/InsertQuery.java
+++ b/jOOQ/src/main/java/org/jooq/InsertQuery.java
@@ -232,6 +232,10 @@ public interface InsertQuery<R extends Record> extends StoreQuery<R>, Insert<R>
      * must assure transactional integrity between the two statements.</li>
      * </ul>
      *
+     * @return The returned value as specified by any of the
+     *         {@link #setReturning()} methods. This may return
+     *         <code>null</code> in case jOOQ could not retrieve any generated
+     *         keys from the JDBC driver.
      * @see #getReturnedRecords()
      */
     @Support
@@ -257,8 +261,15 @@ public interface InsertQuery<R extends Record> extends StoreQuery<R>, Insert<R>
      * other fields are requested, a second statement is issued. Client code
      * must assure transactional integrity between the two statements.</li>
      * </ul>
-     * <p>
-     * This currently only works well for DB2, HSQLDB, MySQL, and Postgres
+     *
+     * @return The returned values as specified by any of the
+     *         {@link #setReturning()} methods. Note:
+     *         <ul>
+     *         <li>Not all databases / JDBC drivers support returning several
+     *         values on multi-row inserts!</li><li>This may return an empty
+     *         <code>Result</code> in case jOOQ could not retrieve any generated
+     *         keys from the JDBC driver.</li>
+     *         </ul>
      */
     @Support
     Result<R> getReturnedRecords();
diff --git a/jOOQ/src/main/java/org/jooq/InsertResultStep.java b/jOOQ/src/main/java/org/jooq/InsertResultStep.java
index 320d0068b1..0477ac1de2 100644
--- a/jOOQ/src/main/java/org/jooq/InsertResultStep.java
+++ b/jOOQ/src/main/java/org/jooq/InsertResultStep.java
@@ -76,7 +76,16 @@ public interface InsertResultStep<R extends Record> extends Insert<R> {
      * <p>
      * This currently only works well for DB2, HSQLDB, MySQL, and Postgres
      *
+     * @return The returned values as specified by the
+     *         {@link InsertReturningStep}. Note:
+     *         <ul>
+     *         <li>Not all databases / JDBC drivers support returning several
+     *         values on multi-row inserts!</li><li>This may return an empty
+     *         <code>Result</code> in case jOOQ could not retrieve any generated
+     *         keys from the JDBC driver.</li>
+     *         </ul>
      * @throws DataAccessException if something went wrong executing the query
+     * @see InsertQuery#getReturnedRecords()
      */
     @Support
     Result<R> fetch() throws DataAccessException;
@@ -85,7 +94,12 @@ public interface InsertResultStep<R extends Record> extends Insert<R> {
      * The record holding returned values as specified by the
      * {@link InsertReturningStep}
      *
+     * @return The returned value as specified by the
+     *         {@link InsertReturningStep}. This may return <code>null</code> in
+     *         case jOOQ could not retrieve any generated keys from the JDBC
+     *         driver.
      * @throws DataAccessException if something went wrong executing the query
+     * @see InsertQuery#getReturnedRecord()
      */
     @Support
     R fetchOne() throws DataAccessException;