diff --git a/jOOQ/src/main/java/org/jooq/ConverterProvider.java b/jOOQ/src/main/java/org/jooq/ConverterProvider.java
index e5506020ae..de878cfe1c 100644
--- a/jOOQ/src/main/java/org/jooq/ConverterProvider.java
+++ b/jOOQ/src/main/java/org/jooq/ConverterProvider.java
@@ -50,6 +50,15 @@ import org.jetbrains.annotations.Nullable;
  * {@link RecordMapper}, e.g. when mapping {@link JSON} or {@link XML} data
  * types onto POJO types using third party libraries like Jackson, Gson, JAXB,
  * or others.
+ * <p>
+ * The general expectation is for a {@link ConverterProvider} to be side-effect
+ * free. Two calls to {@link #provide(Class, Class)} should always produce the
+ * same {@link Converter} logic and thus conversion behaviour, irrespective of
+ * context, other than the {@link Configuration} that hosts the
+ * {@link Configuration#converterProvider()}. This effectively means that it is
+ * possible for jOOQ to cache the outcome of a {@link #provide(Class, Class)}
+ * call within the context of a {@link Configuration} or any derived context,
+ * such as an {@link ExecuteContext}, to greatly improve performance.
  *
  * @author Lukas Eder
  */
diff --git a/jOOQ/src/main/java/org/jooq/RecordMapperProvider.java b/jOOQ/src/main/java/org/jooq/RecordMapperProvider.java
index 1c8d4c2c60..f859206233 100644
--- a/jOOQ/src/main/java/org/jooq/RecordMapperProvider.java
+++ b/jOOQ/src/main/java/org/jooq/RecordMapperProvider.java
@@ -83,6 +83,16 @@ import org.jetbrains.annotations.NotNull;
  * While not strictly required, it is advisable to implement a
  * <code>RecordMapperProvider</code> whose behaviour is consistent with the
  * configured {@link RecordUnmapperProvider}.
+ * <p>
+ * The general expectation is for a {@link RecordMapperProvider} to be
+ * side-effect free. Two calls to {@link #provide(RecordType, Class)} should
+ * always produce the same {@link RecordMapper} logic and thus mapping
+ * behaviour, irrespective of context, other than the {@link Configuration} that
+ * hosts the {@link Configuration#recordMapperProvider()}. This effectively
+ * means that it is possible for jOOQ to cache the outcome of a
+ * {@link #provide(RecordType, Class)} call within the context of a
+ * {@link Configuration} or any derived context, such as an
+ * {@link ExecuteContext}, to greatly improve performance.
  *
  * @author Lukas Eder
  * @see RecordMapper