From d2a7e33fdbb10a2cc8105878ce4705fdf5b02b52 Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Wed, 29 Sep 2021 13:28:16 +0200 Subject: [PATCH] [jOOQ/jOOQ#12470] Add better Javadoc documentation about what Class literals can be passed to DSL.val(Object, Class), etc. --- jOOQ/src/main/java/org/jooq/impl/DSL.java | 90 ++++++++++++++++------- 1 file changed, 64 insertions(+), 26 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/impl/DSL.java b/jOOQ/src/main/java/org/jooq/impl/DSL.java index a60f6e4d6f..777f3cc42b 100644 --- a/jOOQ/src/main/java/org/jooq/impl/DSL.java +++ b/jOOQ/src/main/java/org/jooq/impl/DSL.java @@ -12002,6 +12002,10 @@ public class DSL { * // ... will render this SQL by default, using the SQL Server dialect * [MY_SCHEMA].[MY_SEQUENCE] * + * + * @param name The sequence name + * @param type The sequence type (a type that is supported by + * {@link SQLDataType}) */ @NotNull @Support({ CUBRID, DERBY, FIREBIRD, H2, HSQLDB, MARIADB, POSTGRES, YUGABYTE }) @@ -12126,6 +12130,10 @@ public class DSL { * // ... will execute this SQL on SQL Server: * select length([TITLE]) from [T_BOOK] * + * + * @param name The field name + * @param type The field type (a type that is supported by + * {@link SQLDataType}) */ @NotNull @Support @@ -12257,6 +12265,10 @@ public class DSL { + + + + @@ -13409,8 +13421,9 @@ public class DSL { * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! * - * @param sql The SQL - * @param type The field type + * @param sql The sequence name + * @param type The sequence type (a type that is supported by + * {@link SQLDataType}) * @return A field wrapping the plain SQL * @see SQL * @deprecated - 3.10 - [#6162] - Use {@link #sequence(Name, Class)} instead. @@ -13600,7 +13613,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param sql The SQL - * @param type The field type + * @param type The field type (a type that is supported by + * {@link SQLDataType}) * @return A field wrapping the plain SQL * @see SQL */ @@ -13631,7 +13645,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param sql The SQL - * @param type The field type + * @param type The field type (a type that is supported by + * {@link SQLDataType}) * @return A field wrapping the plain SQL * @see SQL */ @@ -13662,7 +13677,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param sql The SQL - * @param type The field type + * @param type The field type (a type that is supported by + * {@link SQLDataType}) * @param bindings The bindings for the field * @return A field wrapping the plain SQL * @see SQL @@ -13871,7 +13887,8 @@ public class DSL { * * @param sql The SQL clause, containing {numbered placeholders} where query * parts can be injected - * @param type The field type + * @param type The field type (a type that is supported by + * {@link SQLDataType}) * @param parts The {@link QueryPart} objects that are rendered at the * {numbered placeholder} locations * @return A field wrapping the plain SQL @@ -13895,7 +13912,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param name The function name (without parentheses) - * @param type The function return type + * @param type The function return type (a type that is supported by + * {@link SQLDataType}) * @param arguments The function arguments * @see SQL */ @@ -13932,7 +13950,8 @@ public class DSL { * functions that are not yet or insufficiently supported by jOOQ. * * @param name The function name (possibly qualified) - * @param type The function return type + * @param type The function return type (a type that is supported by + * {@link SQLDataType}) * @param arguments The function arguments */ @NotNull @@ -13970,9 +13989,8 @@ public class DSL { } /** - * aggregate() can be used to access native or - * user-defined aggregate functions that are not yet or insufficiently - * supported by jOOQ. + * aggregate() can be used to access native or user-defined + * aggregate functions that are not yet or insufficiently supported by jOOQ. *

* NOTE: When inserting plain SQL into jOOQ objects, you must * guarantee syntax integrity. You may also create the possibility of @@ -13980,7 +13998,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param name The aggregate function name (possibly qualified) - * @param type The aggregate function return type + * @param type The aggregate function return type (a type that is supported + * by {@link SQLDataType}) * @param arguments The aggregate function arguments * @see SQL */ @@ -14014,12 +14033,12 @@ public class DSL { } /** - * aggregate() can be used to access native or - * user-defined aggregate functions that are not yet or insufficiently - * supported by jOOQ. + * aggregate() can be used to access native or user-defined + * aggregate functions that are not yet or insufficiently supported by jOOQ. * * @param name The aggregate function name (possibly qualified) - * @param type The aggregate function return type + * @param type The aggregate function return type (a type that is supported + * by {@link SQLDataType}) * @param arguments The aggregate function arguments */ @NotNull @@ -14054,7 +14073,8 @@ public class DSL { * escape literals when concatenated into SQL clauses! * * @param name The aggregate function name (possibly qualified) - * @param type The aggregate function return type + * @param type The aggregate function return type (a type that is supported + * by {@link SQLDataType}) * @param arguments The aggregate function arguments * @see SQL */ @@ -14093,7 +14113,8 @@ public class DSL { * supported by jOOQ. * * @param name The aggregate function name (possibly qualified) - * @param type The aggregate function return type + * @param type The aggregate function return type (a type that is supported + * by {@link SQLDataType}) * @param arguments The aggregate function arguments */ @NotNull @@ -15113,6 +15134,9 @@ public class DSL { /** * Coerce this field to another type. * + * @param value The value to be coerced + * @param as The field type (a type that is supported by + * {@link SQLDataType}) * @see #coerce(Field, Class) */ @NotNull @@ -15190,8 +15214,9 @@ public class DSL { * * * @param The generic type of the coerced field - * @param field The field to be coerced - * @param as The type that is used for the coercion + * @param value The value to be coerced + * @param as The field type (a type that is supported by + * {@link SQLDataType}) * @return The coerced field * @see Field#coerce(DataType) * @see Field#cast(Class) @@ -15321,7 +15346,8 @@ public class DSL { * * @param The generic type of the cast field * @param value The value to cast - * @param type The type that is used for the cast + * @param type The type that is used for the cast (a type that is supported + * by {@link SQLDataType}) * @return The cast field */ @NotNull @@ -15335,7 +15361,8 @@ public class DSL { * * @param The generic type of the cast field * @param field The field to cast - * @param type The type that is used for the cast + * @param type The type that is used for the cast (a type that is supported + * by {@link SQLDataType}) * @return The cast field */ @NotNull @@ -26062,6 +26089,9 @@ public class DSL { /** * Create a named parameter with a defined type and no initial value. * + * @param name The parameter name + * @param type The type that is used for the parameter (a type that is + * supported by {@link SQLDataType}) * @see #param(String, Object) */ @NotNull @@ -26549,9 +26579,12 @@ public class DSL { } /** - * A synonym for {@link #val(Object, Class)} to be used in Scala and Groovy, where - * val is a reserved keyword. + * A synonym for {@link #val(Object, Class)} to be used in Scala and Groovy, + * where val is a reserved keyword. * + * @param value The bind value + * @param type The type that is used for the bind value (a type that is + * supported by {@link SQLDataType}) * @see #val(Object, Class) */ @NotNull @@ -27477,6 +27510,9 @@ public class DSL { *

  • field("abc'def") renders abc'def
    • * * + * @param value The inline value + * @param type The data type to enforce upon the value (a type that is + * supported by {@link SQLDataType}) * @see #val(Object, Class) */ @NotNull @@ -27954,7 +27990,8 @@ public class DSL { * * @param The generic value type * @param value The constant value - * @param type The data type to enforce upon the value + * @param type The data type to enforce upon the value (a type that is + * supported by {@link SQLDataType}) * @return A field representing the constant value * @see #val(Object, DataType) */ @@ -29850,7 +29887,8 @@ public class DSL { * {@link SQLDialect} and a given Java type. * * @param The generic type - * @param type The Java type + * @param type The Java type. This must be a type supported by + * {@link SQLDataType}. * @return The DSL's underlying default data type. * @deprecated - 3.11.0 - [#7483] - The (indirect) use of the internal * static data type registry is not recommended.