[#5618] Further improve select() Javadoc for empty argument lists

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

@@ -4410,7 +4410,13 @@ public interface DSLContext extends Scope , AutoCloseable  {
      * </pre></code>
      * <p>
      * Note that passing an empty collection conveniently produces
-     * <code>SELECT *</code> semantics.
+     * <code>SELECT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSL#select(Collection)
      */
@@ -4437,8 +4443,14 @@ public interface DSLContext extends Scope , AutoCloseable  {
      *       .execute();
      * </pre></code>
      * <p>
-     * Note that passing an empty array (e.g. by not passing any vararg
-     * argument) conveniently produces <code>SELECT *</code> semantics.
+     * Note that passing an empty collection conveniently produces
+     * <code>SELECT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSL#select(Field...)
      */
@@ -5129,7 +5141,13 @@ public interface DSLContext extends Scope , AutoCloseable  {
      * </pre></code>
      * <p>
      * Note that passing an empty collection conveniently produces
-     * <code>SELECT DISTINCT *</code> semantics.
+     * <code>SELECT DISTINCT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT DISTINCT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT DISTINCT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSL#selectDistinct(Collection)
      */
@@ -5155,8 +5173,14 @@ public interface DSLContext extends Scope , AutoCloseable  {
      *       .orderBy(field2);
      * </pre></code>
      * <p>
-     * Note that passing an empty array (e.g. by not passing any vararg
-     * argument) conveniently produces <code>SELECT DISTINCT *</code> semantics.
+     * Note that passing an empty collection conveniently produces
+     * <code>SELECT DISTINCT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT DISTINCT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT DISTINCT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSL#selectDistinct(Field...)
      */

jOOQ/src/main/java/org/jooq/impl/DSL.java

@@ -1802,7 +1802,13 @@ public class DSL {
      * </pre></code>
      * <p>
      * Note that passing an empty collection conveniently produces
-     * <code>SELECT *</code> semantics.
+     * <code>SELECT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSLContext#select(Collection)
      */
@@ -1835,8 +1841,14 @@ public class DSL {
      *  .orderBy(field2);
      * </pre></code>
      * <p>
-     * Note that passing an empty array (e.g. by not passing any vararg
-     * argument) conveniently produces <code>SELECT *</code> semantics.
+     * Note that passing an empty collection conveniently produces
+     * <code>SELECT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSLContext#select(SelectField...)
      */
@@ -2710,7 +2722,13 @@ public class DSL {
      * </pre></code>
      * <p>
      * Note that passing an empty collection conveniently produces
-     * <code>SELECT DISTINCT *</code> semantics.
+     * <code>SELECT DISTINCT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT DISTINCT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT DISTINCT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSLContext#selectDistinct(Collection)
      */
@@ -2743,8 +2761,14 @@ public class DSL {
      *  .orderBy(field2);
      * </pre></code>
      * <p>
-     * Note that passing an empty array (e.g. by not passing any vararg
-     * argument) conveniently produces <code>SELECT DISTINCT *</code> semantics.
+     * Note that passing an empty collection conveniently produces
+     * <code>SELECT DISTINCT *</code> semantics, i.e. it:
+     * <ul>
+     * <li>Renders <code>SELECT DISTINCT tab1.col1, tab1.col2, ..., tabN.colN</code> if
+     * all columns are known</li>
+     * <li>Renders <code>SELECT DISTINCT *</code> if not all columns are known, e.g. when
+     * using plain SQL</li>
+     * </ul>
      *
      * @see DSLContext#selectDistinct(SelectField...)
      */