From e37fe1c0870eeb1157c12c5fae665158ece5bda9 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Fri, 19 Feb 2021 08:43:14 +0100
Subject: [PATCH] [jOOQ/jOOQ#11472] Document immutability of CSVFormat and
 related types

---
 jOOQ/src/main/java/org/jooq/CSVFormat.java   | 3 +++
 jOOQ/src/main/java/org/jooq/ChartFormat.java | 5 +++++
 jOOQ/src/main/java/org/jooq/JSONFormat.java  | 3 +++
 jOOQ/src/main/java/org/jooq/TXTFormat.java   | 6 +++++-
 jOOQ/src/main/java/org/jooq/XMLFormat.java   | 3 +++
 5 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/jOOQ/src/main/java/org/jooq/CSVFormat.java b/jOOQ/src/main/java/org/jooq/CSVFormat.java
index b284904aac..2ea54f48b9 100644
--- a/jOOQ/src/main/java/org/jooq/CSVFormat.java
+++ b/jOOQ/src/main/java/org/jooq/CSVFormat.java
@@ -41,6 +41,9 @@ import static org.jooq.CSVFormat.Quote.SPECIAL_CHARACTERS;
 
 /**
  * A CSV formatting type, which can be used to configure CSV imports / exports.
+ * <p>
+ * The type is immutable, meaning calls to setters like {@link #delimiter(char)}
+ * do not modify the original reference, but return a new one instead.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/ChartFormat.java b/jOOQ/src/main/java/org/jooq/ChartFormat.java
index 73325bfdce..1bb96a472f 100644
--- a/jOOQ/src/main/java/org/jooq/ChartFormat.java
+++ b/jOOQ/src/main/java/org/jooq/ChartFormat.java
@@ -40,6 +40,11 @@ package org.jooq;
 import java.text.DecimalFormat;
 
 /**
+ * A CSV formatting type, which can be used to configure chart exports.
+ * <p>
+ * The type is immutable, meaning calls to setters like {@link #width(int)} do
+ * not modify the original reference, but return a new one instead.
+ *
  * @author Lukas Eder
  */
 public final class ChartFormat {
diff --git a/jOOQ/src/main/java/org/jooq/JSONFormat.java b/jOOQ/src/main/java/org/jooq/JSONFormat.java
index dc7ca5a05e..03d53d4d7e 100644
--- a/jOOQ/src/main/java/org/jooq/JSONFormat.java
+++ b/jOOQ/src/main/java/org/jooq/JSONFormat.java
@@ -60,6 +60,9 @@ import static org.jooq.tools.StringUtils.rightPad;
  * or, using {@link RecordFormat#OBJECT}: <code><pre>
  * [{"field-1": value-1-1, "field-2": value-1-2,..., "field-n": value-1-n},
  *  {"field-1": value-2-1, "field-2": value-2-2,..., "field-n": value-2-n}]</pre></code>
+ * <p>
+ * The type is immutable, meaning calls to setters like {@link #header(boolean)}
+ * do not modify the original reference, but return a new one instead.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/TXTFormat.java b/jOOQ/src/main/java/org/jooq/TXTFormat.java
index 84c1c40840..1bea21c470 100644
--- a/jOOQ/src/main/java/org/jooq/TXTFormat.java
+++ b/jOOQ/src/main/java/org/jooq/TXTFormat.java
@@ -39,7 +39,11 @@ package org.jooq;
 
 
 /**
- * A CSV formatting type, which can be used to configure CSV imports / exports.
+ * A text formatting type, which can be used to configure text imports /
+ * exports.
+ * <p>
+ * The type is immutable, meaning calls to setters like {@link #maxRows(int)} do
+ * not modify the original reference, but return a new one instead.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/XMLFormat.java b/jOOQ/src/main/java/org/jooq/XMLFormat.java
index b9b03937dd..d49495148d 100644
--- a/jOOQ/src/main/java/org/jooq/XMLFormat.java
+++ b/jOOQ/src/main/java/org/jooq/XMLFormat.java
@@ -41,6 +41,9 @@ import static org.jooq.tools.StringUtils.rightPad;
 
 /**
  * An XML formatting type, which can be used to configure XML imports / exports.
+ * <p>
+ * The type is immutable, meaning calls to setters like {@link #header(boolean)}
+ * do not modify the original reference, but return a new one instead.
  *
  * @author Lukas Eder
  */