Revise contribution

Closes gh-32380

Author: sbrannen

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterUtils.java

@@ -273,9 +273,10 @@ private static int skipCommentsAndQuotes(char[] statement, int position) {
 	 * parentheses. This allows for the use of "expression lists" in the SQL statement
 	 * like: <br /><br />
 	 * {@code select id, name, state from table where (name, age) in (('John', 35), ('Ann', 50))}
-	 * <p>The parameter values passed in are used to determine the number of placeholders to
-	 * be used for a select list. Select lists should be limited to 100 or fewer elements and not be empty,
-	 * A larger number of or empty elements is not guaranteed to be supported by the database and
+	 * <p>The parameter values passed in are used to determine the number of
+	 * placeholders to be used for a select list. Select lists should not be empty
+	 * and should be limited to 100 or fewer elements. An empty list or a larger
+	 * number of elements is not guaranteed to be supported by the database and
 	 * is strictly vendor-dependent.
 	 * @param parsedSql the parsed representation of the SQL statement
 	 * @param paramSource the source for named parameters
@@ -460,7 +461,7 @@ public static List<SqlParameter> buildSqlParameterList(ParsedSql parsedSql, SqlP
 
 	/**
 	 * Parse the SQL statement and locate any placeholders or named parameters.
-	 * Named parameters are substituted for a JDBC placeholder.
+	 * <p>Named parameters are substituted for a JDBC placeholder.
 	 * <p>This is a shortcut version of
 	 * {@link #parseSqlStatement(String)} in combination with
 	 * {@link #substituteNamedParameters(ParsedSql, SqlParameterSource)}.
@@ -474,9 +475,10 @@ public static String parseSqlStatementIntoString(String sql) {
 
 	/**
 	 * Parse the SQL statement and locate any placeholders or named parameters.
-	 * Named parameters are substituted for a JDBC placeholder and any select list
-	 * is expanded to the required number of placeholders.
+	 * <p>Named parameters are substituted for a JDBC placeholder, and any select
+	 * list is expanded to the required number of placeholders.
 	 * <p>This is a shortcut version of
+	 * {@link #parseSqlStatement(String)} in combination with
 	 * {@link #substituteNamedParameters(ParsedSql, SqlParameterSource)}.
 	 * @param sql the SQL statement
 	 * @param paramSource the source for named parameters

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/NamedParameterUtils.java

@@ -275,9 +275,10 @@ private static int skipCommentsAndQuotes(char[] statement, int position) {
 	 * and in that case the placeholders will be grouped and enclosed with parentheses.
 	 * This allows for the use of "expression lists" in the SQL statement like:
 	 * {@code select id, name, state from table where (name, age) in (('John', 35), ('Ann', 50))}
-	 * <p>The parameter values passed in are used to determine the number of placeholders to
-	 * be used for a select list. Select lists should be limited to 100 or fewer elements.
-	 * A larger number of elements is not guaranteed to be supported by the database and
+	 * <p>The parameter values passed in are used to determine the number of
+	 * placeholders to be used for a select list. Select lists should not be empty
+	 * and should be limited to 100 or fewer elements. An empty list or a larger
+	 * number of elements is not guaranteed to be supported by the database and
 	 * is strictly vendor-dependent.
 	 * @param parsedSql the parsed representation of the SQL statement
 	 * @param bindMarkersFactory the bind marker factory.
@@ -361,8 +362,11 @@ private static boolean isParameterSeparator(char c) {
 
 	/**
 	 * Parse the SQL statement and locate any placeholders or named parameters.
-	 * Named parameters are substituted for a native placeholder and any
+	 * <p>Named parameters are substituted for a native placeholder and any
 	 * select list is expanded to the required number of placeholders.
+	 * <p>This is a shortcut version of
+	 * {@link #parseSqlStatement(String)} in combination with
+	 * {@link #substituteNamedParameters(ParsedSql, BindMarkersFactory, BindParameterSource)}.
 	 * @param sql the SQL statement
 	 * @param bindMarkersFactory the bind marker factory
 	 * @param paramSource the source for named parameters