From afe156a7e3272471706c6afd6aa39dd85ff74be3 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Wed, 23 Feb 2022 15:48:36 +0100
Subject: [PATCH] [jOOQ/jOOQ#4727] Added some Javadoc to Table

---
 jOOQ/src/main/java/org/jooq/Table.java | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/jOOQ/src/main/java/org/jooq/Table.java b/jOOQ/src/main/java/org/jooq/Table.java
index c49f792c92..4737cab8ce 100644
--- a/jOOQ/src/main/java/org/jooq/Table.java
+++ b/jOOQ/src/main/java/org/jooq/Table.java
@@ -121,6 +121,20 @@ import org.jetbrains.annotations.Nullable;
  * </pre></code>
  * <p>
  * Instances can be created using {@link DSL#table(Name)} and overloads.
+ * <p>
+ * <h3>Using table references as field expressions</h3>
+ * <p>
+ * Table references can be used like {@link Field} in queries. This includes:
+ * <ul>
+ * <li>A {@link GroupField} is an expression that is used in a {@link Select}
+ * query's <code>GROUP BY</code> clause.</li>
+ * <li>A {@link SelectField} is an expression that is used in a {@link Select}
+ * query's <code>SELECT</code> clause, or in a DML query's
+ * <code>RETURNING</code> clause, such as <code>INSERT .. RETURNING</code>.</li>
+ * </ul>
+ * <p>
+ * Other types of {@link Table} cannot be used this way, even if the type system
+ * cannot prevent this.
  *
  * @param <R> The record type associated with this table
  * @author Lukas Eder