Provide actual information in javadoc of JdbcStatement.getGeneratedKeys()

h2/src/main/org/h2/jdbc/JdbcStatement.java

@@ -818,12 +818,49 @@ public class JdbcStatement extends TraceObject implements Statement, JdbcStateme
     }
 
     /**
-     * Return a result set that contains the last generated auto-increment key
-     * for this connection, if there was one. If no key was generated by the
-     * last modification statement, then an empty result set is returned.
-     * The returned result set only contains the data for the very last row.
+     * Return a result set with generated keys from the latest executed command or
+     * an empty result set if keys were not generated or were not requested with
+     * {@link Statement#RETURN_GENERATED_KEYS}, column indexes, or column names.
+     * <p>
+     * Generated keys are only returned from inserted rows from {@code INSERT},
+     * {@code MERGE INTO}, and {@code MERGE INTO ... USING} commands. Generated keys
+     * are not returned if exact values of generated columns were specified
+     * explicitly in SQL command. All columns with inserted generated values are
+     * included in the result if command was executed with
+     * {@link Statement#RETURN_GENERATED_KEYS} parameter.
+     * </p>
+     * <p>
+     * If SQL command inserts multiple rows with generated keys each such inserted
+     * row is returned. Batch methods are also supported. When multiple rows are
+     * returned each row contains only generated values for this row. It's possible
+     * to insert several rows with generated values in different columns with some
+     * specific commands, in this special case the returned result set contains all
+     * used columns, but each row will contain only generated values, columns that
+     * were not generated for this row will contain {@code null} values.
+     * </p>
+     * <p>
+     * H2 treats inserted value as generated in the following cases:
+     * </p>
+     * <ul>
+     * <li>Columns with sequences including {@code IDENTITY} columns and columns
+     * with {@code AUTO_INCREMENT} if value was generated automatically (not
+     * specified in command).</li>
+     * <li>Columns with other default values that are not evaluated into constant
+     * expressions (like {@code DEFAULT RANDOM_UUID()}) also only if default value
+     * was inserted.</li>
+     * <li>Columns that were set by triggers.</li>
+     * <li>Columns with values specified in command with invocation of some sequence
+     * (like {@code INSERT INTO ... VALUES (NEXT VALUE FOR ...)}).</li>
+     * </ul>
+     * <p>
+     * Exact required columns for the returning result set may be specified on
+     * execution of command with names or indexes of columns to limit output or
+     * reorder columns in result set. Specifying of some column has no effect on
+     * treatment of inserted values as generated or not. If some value is not
+     * determined to be generated it will not be returned even on explicit request.
+     * </p>
      *
-     * @return the result set with one row and one column containing the key
+     * @return the possibly empty result set with generated keys
      * @throws SQLException if this object is closed
      */
     @Override