[#8240] Add a Javadoc link from all org.jooq.XYZ types to their respective DSL.xyz() constructor method

jOOQ/src/main/java/org/jooq/AggregateFunction.java

@@ -41,11 +41,16 @@ package org.jooq;
 
 import java.util.Collection;
 
+import org.jooq.impl.DSL;
+
 
 /**
  * An aggregate function is a special field that is usually used in a
  * <code>GROUP BY</code> context. It is also the base for window function
  * construction.
+ * <p>
+ * Instances can be created using various {@link DSL} methods and their
+ * overloads, such as {@link DSL#count()} or {@link DSL#countDistinct(Field)}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Asterisk.java

@@ -37,10 +37,13 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
 
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>SELECT</code>
  * clauses.
+ * <p>
+ * Instances can be created using {@link DSL#asterisk()}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Block.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
- * A query that models an anonymous procedural block
+ * A query that models an anonymous procedural block.
+ * <p>
+ * Instances can be created using {@link DSL#begin(Statement...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Catalog.java

@@ -40,8 +40,12 @@ package org.jooq;
 import java.util.List;
 import java.util.stream.Stream;
 
+import org.jooq.impl.DSL;
+
 /**
  * An object representing a database catalog.
+ * <p>
+ * Instances can be created using {@link DSL#catalog(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Collation.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
  * A collation.
+ * <p>
+ * Instances can be created using {@link DSL#collation(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Comment.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
  * A meta model for SQL comments on tables, fields, etc.
+ * <p>
+ * Instances can be created using {@link DSL#comment(String)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/CommonTableExpression.java

@@ -40,6 +40,8 @@ package org.jooq;
 /**
  * A common table expression is a table that can be supplied to
  * <code>WITH</code> clauses.
+ * <p>
+ * Instances can be created using {@link Name#as(Select)}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Condition.java

@@ -42,7 +42,11 @@ import org.jooq.impl.DSL;
 
 
 /**
- * A condition to be used in a query's where part
+ * A condition to be used in a query's where part.
+ * <p>
+ * Instances can be created using {@link DSL#condition(Field)} and overloads, or
+ * by calling a comparison operator method on {@link Field}, such as
+ * {@link Field#eq(Field)}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Constraint.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
  * A DDL constraint.
+ * <p>
+ * Instances can be created using {@link DSL#constraint(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Declaration.java

@@ -58,6 +58,10 @@ package org.jooq;
 
 
 
+
+
+
+
 
 
 

jOOQ/src/main/java/org/jooq/Delete.java

@@ -37,9 +37,14 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
 
 /**
  * A {@link Query} that can delete data in the database.
+ * <p>
+ * Instances can be created using {@link DSL#deleteFrom(Table)},
+ * {@link DSLContext#deleteFrom(Table)}, or
+ * {@link DSLContext#deleteQuery(Table)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DeleteQuery.java

@@ -47,7 +47,9 @@ import static org.jooq.SQLDialect.POSTGRES;
 import java.util.Collection;
 
 /**
- * A query used for deletion of data
+ * A query used for deletion of data.
+ * <p>
+ * Instances can be created using {@link DSLContext#deleteQuery(Table)}.
  *
  * @param <R> The record type of the table being deleted from
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/DerivedColumnList.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList1.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList10.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList11.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList12.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList13.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList14.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList15.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList16.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList17.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList18.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList19.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList2.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList20.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList21.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList22.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList3.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList4.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList5.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList6.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList7.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList8.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/DerivedColumnList9.java

@@ -57,7 +57,9 @@ import static org.jooq.SQLDialect.POSTGRES;
  * optional derived column list.
  * <p>
  * An example of a correlation name with derived column list is:
- * <code>table(column1, column2)</code>
+ * <code>table(column1, column2)</code>.
+ * <p>
+ * Instances can be created using {@link Name#fields(String...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/False.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
  * A predicate that always yields <code>false</code>.
+ * <p>
+ * Instances can be created using {@link DSL#falseCondition()}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Field.java

@@ -75,10 +75,21 @@ import org.jooq.types.Interval;
 // ...
 
 /**
- * A field used in tables and conditions
+ * A field used in tables and conditions.
  * <p>
  * Note that all fields qualify as {@link GroupField}, i.e. they can always be
- * used in <code>GROUP BY</code> clauses
+ * used in <code>GROUP BY</code> clauses.
+ * <p>
+ * Instances can be created using a variety of ways, including:
+ * <ul>
+ * <li>{@link DSL#field(String)} and overloads for plain SQL field
+ * expression.</li>
+ * <li>{@link DSL#field(Name)} and overloads for field identifier
+ * references.</li>
+ * <li>{@link DSL#field(Condition)} for predicates as fields.</li>
+ * <li>{@link DSL#field(Select)} for correlated subqueries.</li>
+ * <li>Fields referenced from generated tables</li>
+ * </ul>
  *
  * @param <T> The field type
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/FieldLike.java

@@ -42,7 +42,9 @@ import java.util.function.Function;
 import org.jooq.conf.Settings;
 
 /**
- * An object that can behave like a field (a field-like object)
+ * An object that can behave like a field (a field-like object).
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/FieldOrConstraint.java

@@ -42,6 +42,8 @@ package org.jooq;
  * both types alike.
  * <p>
  * This is useful for DDL statements.
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/FieldOrRow.java

@@ -50,6 +50,8 @@ package org.jooq;
  * ROLLUP ( a, (b,c), d )
  * </code>
  * </pre>
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/ForeignKey.java

@@ -44,6 +44,9 @@ import org.jooq.exception.DataAccessException;
 /**
  * A <code>ForeignKey</code> is an object referencing a {@link UniqueKey}. It
  * represents a <code>FOREIGN KEY</code> relationship between two tables.
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @param <R> The <code>FOREIGN KEY</code>'s owner table record
  * @param <O> The referenced <code>KEY</code>'s owner table record

jOOQ/src/main/java/org/jooq/GroupField.java

@@ -37,10 +37,14 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
 
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>GROUP BY</code>
- * clauses
+ * clauses.
+ * <p>
+ * Instances can be created using {@link DSL#groupingSets(Field[][])} and
+ * related methods, or by creating a subtype.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Identity.java

@@ -44,6 +44,9 @@ import java.io.Serializable;
  * column as understood by the SQL:2003 standard. In most RDBMS, this is
  * actually called an <code>IDENTITY</code> column. Some RDMBS such as MySQL
  * call it <code>AUTO_INCREMENT</code> columns.
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @param <R> The <code>IDENTITY</code>'s owner table record
  * @param <T> The <code>IDENTITY</code>'s field type

jOOQ/src/main/java/org/jooq/Index.java

@@ -39,8 +39,12 @@ package org.jooq;
 
 import java.util.List;
 
+import org.jooq.impl.DSL;
+
 /**
  * A DDL index definition.
+ * <p>
+ * Instances can be created using {@link DSL#index(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Insert.java

@@ -37,8 +37,13 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
  * A {@link Query} that can insert data in the database.
+ * <p>
+ * Instances can be created using {@link DSL#insertInto(Table)}, or
+ * {@link DSLContext#insertQuery(Table)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/InsertQuery.java

@@ -65,7 +65,10 @@ import java.util.Collection;
 import java.util.Map;
 
 /**
- * A query for data insertion
+ * A query for data insertion.
+ * <p>
+ * Instances can be created using {@link DSLContext#insertQuery(Table)} and
+ * overloads.
  *
  * @param <R> The record type of the table being inserted into
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/JoinType.java

@@ -65,7 +65,7 @@ import static org.jooq.SQLDialect.POSTGRES;
 import org.jooq.impl.DSL;
 
 /**
- * The type of join
+ * The type of join.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Key.java

@@ -44,6 +44,9 @@ import java.util.List;
 /**
  * A <code>Key</code> is an object representing a <code>UNIQUE KEY</code>, a
  * <code>PRIMARY KEY</code>, or a <code>FOREIGN KEY</code>.
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @param <R> The <code>KEY</code>'s owner table record
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/Keyword.java

@@ -38,6 +38,7 @@
 package org.jooq;
 
 import org.jooq.conf.Settings;
+import org.jooq.impl.DSL;
 
 /**
  * A SQL keyword <code>QueryPart</code>.
@@ -45,6 +46,8 @@ import org.jooq.conf.Settings;
  * A <code>Keyword</code> is a {@link QueryPart} that renders a SQL keyword
  * according to the settings specified in
  * {@link Settings#getRenderKeywordCase()}.
+ * <p>
+ * Instances can be created using {@link DSL#keyword(String)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Label.java

@@ -52,4 +52,8 @@ package org.jooq;
 
 
 
+
+
+
+
             

jOOQ/src/main/java/org/jooq/Link.java

@@ -52,6 +52,10 @@ package org.jooq;
 
 
 
+
+
+
+
 
 
 

jOOQ/src/main/java/org/jooq/Merge.java

@@ -37,9 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
 
 /**
  * A {@link Query} that can merge data in the database.
+ * <p>
+ * Instances can be created using {@link DSL#mergeInto(Table)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Name.java

@@ -61,6 +61,7 @@ import java.util.function.Function;
 
 import org.jooq.conf.RenderQuotedNames;
 import org.jooq.conf.Settings;
+import org.jooq.impl.DSL;
 
 /**
  * A SQL identifier <code>QueryPart</code>.
@@ -69,6 +70,8 @@ import org.jooq.conf.Settings;
  * according to the settings specified in
  * {@link Settings#getRenderQuotedNames()} and
  * {@link Settings#getRenderNameCase()}.
+ * <p>
+ * Instances can be created using {@link DSL#name(String)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Named.java

@@ -39,6 +39,8 @@ package org.jooq;
 
 /**
  * A common base type for all qualifiable, named objects.
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/OrderField.java

@@ -41,6 +41,8 @@ package org.jooq;
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>ORDER BY</code>
  * clauses.
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Package.java

@@ -40,7 +40,10 @@ package org.jooq;
 /**
  * A container for stored procedures and functions
  * <p>
- * This is only supported in the {@link SQLDialect#ORACLE} dialect
+ * This is only supported in the {@link SQLDialect#ORACLE} dialect.
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Param.java

@@ -44,6 +44,9 @@ import org.jooq.tools.Convert;
 
 /**
  * A named parameter and/or bind value.
+ * <p>
+ * Instances can be created using {@link DSL#param(String, Object)},
+ * {@link DSL#val(Object)}, {@link DSL#inline(Object)} and respective overloads.
  *
  * @author Lukas Eder
  * @see DSL#param(String, Object)

jOOQ/src/main/java/org/jooq/Parameter.java

@@ -41,6 +41,9 @@ package org.jooq;
 
 /**
  * A parameter to a stored procedure or function.
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @param <T> The parameter type
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/Privilege.java

@@ -37,7 +37,13 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
+ * A privilege for use in <code>GRANT</code> statements.
+ * <p>
+ * Instances can be created using {@link DSL#privilege(String)} and overloads.
+ *
  * @author Timur Shaidullin
  */
 public interface Privilege extends QueryPart {

jOOQ/src/main/java/org/jooq/QualifiedAsterisk.java

@@ -41,6 +41,8 @@ package org.jooq;
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>SELECT</code>
  * clauses.
+ * <p>
+ * Instances can be created using {@link Table#asterisk()}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/QuantifiedSelect.java

@@ -37,6 +37,7 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
 
 /**
  * A participant of a quantified comparison predicate
@@ -47,7 +48,10 @@ package org.jooq;
  * <li><code>ANY (SELECT 1 FROM DUAL)</code></li>
  * <li><code>ALL (SELECT 1 FROM DUAL)</code></li>
  * </ul>
- * These predicates can be used exclusively with methods, such as {@link Field}
+ * These predicates can be used exclusively with methods, such as {@link Field}.
+ * <p>
+ * Instances can be created using {@link DSL#any(Select)} and
+ * {@link DSL#all(Select)}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Queries.java

@@ -41,9 +41,12 @@ import java.sql.Statement;
 import java.util.stream.Stream;
 
 import org.jooq.exception.DetachedException;
+import org.jooq.impl.DSL;
 
 /**
  * A wrapper for a collection of queries.
+ * <p>
+ * Instances can be created using {@link DSL#queries(Query...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Query.java

@@ -52,7 +52,10 @@ import org.jooq.exception.DataTypeException;
 import org.jooq.impl.DSL;
 
 /**
- * Any query
+ * Any query.
+ * <p>
+ * Instances can be created using {@link DSL#query(String)} and overloads,
+ * or by creating a subtype.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/QueryPart.java

@@ -43,9 +43,6 @@ import org.jooq.conf.Settings;
 
 /**
  * The common base type for all objects that can be used for query composition.
- * <p>
- * All <code>QueryPart</code> implementations can be cast to
- * {@link QueryPartInternal} in order to access the internal API.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/ResultQuery.java

@@ -64,6 +64,7 @@ import org.jooq.exception.InvalidResultException;
 import org.jooq.exception.MappingException;
 import org.jooq.exception.NoDataFoundException;
 import org.jooq.exception.TooManyRowsException;
+import org.jooq.impl.DSL;
 import org.jooq.impl.DefaultRecordMapper;
 
 /**
@@ -89,6 +90,9 @@ import org.jooq.impl.DefaultRecordMapper;
  * {@link ResultQuery#fetchSize(int)}, might incur additional database
  * roundtrips. If this causes problems, {@link ResultQuery#fetchAny()} may be
  * preferred.
+ * <p>
+ * Instances can be created using {@link DSL#resultQuery(String)} and overloads,
+ * or by creating a subtype.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Role.java

@@ -37,8 +37,12 @@
  */
 package org.jooq;
 
+import org.jooq.impl.DSL;
+
 /**
- * The Role to be used by GRANT statement.
+ * The Role to be used by the <code>GRANT</code> statement.
+ * <p>
+ * Instances can be created using {@link DSL#role(Name)} and overloads.
  *
  * @author Timur Shaidullin
  */

jOOQ/src/main/java/org/jooq/Routine.java

@@ -81,6 +81,9 @@ import org.jooq.exception.DataAccessException;
  * Hence, with #852, jOOQ 1.6.8, the distinction between procedures and
  * functions becomes obsolete. All stored routines are simply referred to as
  * "Routine".
+ * <p>
+ * Instances of this type cannot be created directly. They are available from
+ * generated code.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row.java

@@ -39,12 +39,16 @@ package org.jooq;
 
 import java.util.stream.Stream;
 
+import org.jooq.impl.DSL;
+
 /**
  * A model type for a row value expression.
  * <p>
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row1.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row10.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row11.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row12.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row13.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row14.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row15.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row16.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row17.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row18.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row19.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row2.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row20.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row21.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row22.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row3.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row4.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row5.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row6.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row7.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row8.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Row9.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/RowId.java

@@ -42,6 +42,8 @@ import java.sql.Types;
 
 /**
  * A data type corresponding to JDBC's {@link Types#ROWID}.
+ * <p>
+ * Instances can be created using {@link Table#rowid()}.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/RowN.java

@@ -68,6 +68,8 @@ import java.util.Collection;
  * Note: Not all databases support row value expressions, but many row value
  * expression operations can be emulated on all databases. See relevant row
  * value expression method Javadocs for details.
+ * <p>
+ * Instances can be created using {@link DSL#row(Object...)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/SQL.java

@@ -91,6 +91,8 @@ import org.jooq.impl.DSL;
  * positions (outside of comments, string literals, quoted name literals) and
  * substitute the appropriate bind value into the template.</li>
  * </ul>
+ * <p>
+ * Instances can be created using {@link DSL#sql(String)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Schema.java

@@ -41,8 +41,12 @@ package org.jooq;
 import java.util.List;
 import java.util.stream.Stream;
 
+import org.jooq.impl.DSL;
+
 /**
  * An object representing a database schema.
+ * <p>
+ * Instances can be created using {@link DSL#schema(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Select.java

@@ -62,9 +62,13 @@ import static org.jooq.SQLDialect.SQLITE;
 import java.util.List;
 
 import org.jooq.exception.DataAccessException;
+import org.jooq.impl.DSL;
 
 /**
- * A {@link Query} that can provide a {@link Result} after execution
+ * A {@link Query} that can provide a {@link Result} after execution.
+ * <p>
+ * Instances can be created using {@link DSL#select(SelectFieldOrAsterisk...)},
+ * or {@link DSLContext#selectQuery()} and overloads.
  *
  * @param <R> The record type being returned by this query
  * @author Lukas Eder

jOOQ/src/main/java/org/jooq/SelectField.java

@@ -41,6 +41,8 @@ package org.jooq;
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>SELECT</code>
  * clauses.
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/SelectFieldOrAsterisk.java

@@ -41,6 +41,8 @@ package org.jooq;
 /**
  * A <code>QueryPart</code> to be used exclusively in <code>SELECT</code>
  * clauses.
+ * <p>
+ * Instances of this type cannot be created directly, only of its subtypes.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/SelectQuery.java

@@ -74,7 +74,9 @@ import java.util.Collection;
 import org.jooq.exception.DataAccessException;
 
 /**
- * A query for data selection
+ * A query for data selection.
+ * <p>
+ * Instances can be created using {@link DSLContext#selectQuery()} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/Sequence.java

@@ -52,8 +52,12 @@ import static org.jooq.SQLDialect.POSTGRES;
 // ...
 // ...
 
+import org.jooq.impl.DSL;
+
 /**
  * A type representing sequences in databases that support this.
+ * <p>
+ * Instances can be created using {@link DSL#sequence(Name)} and overloads.
  *
  * @author Lukas Eder
  */

jOOQ/src/main/java/org/jooq/SortField.java

@@ -39,7 +39,10 @@ package org.jooq;
 
 
 /**
- * A wrapper for a {@link Field} and a {@link SortField}
+ * A wrapper for a {@link Field} and a {@link SortField}.
+ * <p>
+ * Instances can be created using {@link Field#asc()}, {@link Field#desc()} and
+ * related methods.
  *
  * @param <T> The field type
  * @author Lukas Eder