rationalize the supported query return types

see #503

api/src/main/java/jakarta/data/repository/Find.java

@@ -45,25 +45,18 @@
  * a list of Car objects based on the provided model parameter in a database.
  * </p>
  *
- * <p>The return type of a method annotated with {@code @Find} must be one of the following:</p>
+ * <p>A method annotated with {@code @Find} must return one of the following types:</p>
  * <ul>
- *     <li>{@code List}</li>
- *     <li>{@code Page}</li>
- *     <li>{@code Slice}</li>
- *     <li>{@code KeysetAwarePage}</li>
- *     <li>{@code KeysetAwareSlice}</li>
- *     <li>{@code Set}</li>
- *     <li>{@code Stream}</li>
- *     <li>{@code Streamable}</li>
- *     <li>{@code Iterable}</li>
- *     <li>{@code Collection}</li>
- *     <li>{@code Optional} (for single instances)</li>
- *     <li>The entity type itself (for single instances)</li>
- *     <li>Array of the entity type</li>
+ *     <li>an entity type {@code E}, when the method returns a single instance,</li>
+ *     <li>{@code Optional<E>}, when the method returns at most a single instance,</li>
+ *     <li>an entity array type {@code E[]},
+ *     <li>{@code List<E>},</li>
+ *     <li>{@code Stream<E>}, or</li>
+ *     <li>{@code Page<E>}, {@code Slice<E>}, {@code KeysetAwarePage<E>}, or {@code KeysetAwareSlice<E>}.</li>
  * </ul>
  *
  * <p>If the annotated method return type is a single instance (either through {@code Optional} or directly), but the
- * query returns more than one element, it will throw a {@link jakarta.data.exceptions.NonUniqueResultException}.
+ * query returns more than one element, the method must throw {@link jakarta.data.exceptions.NonUniqueResultException}.
  * </p>
  * <p>Annotations such as {@code @Find}, {@code @Query}, {@code @Insert}, {@code @Update}, {@code @Delete}, and
  * {@code @Save} are mutually-exclusive. A given method of a repository interface may have at most one {@code @Find}

api/src/main/java/jakarta/data/repository/OrderBy.java

@@ -90,7 +90,7 @@
      *
      * <p>The default value is <code>false</code>.</p>
      *
-     * @return whether or not to request case insensitive sorting for the property.
+     * @return whether to request case-insensitive sorting for the property.
      */
     boolean ignoreCase() default false;
 

api/src/main/java/module-info.java

@@ -498,24 +498,20 @@
  * </tr>
  *
  * <tr style="vertical-align: top; background-color:#eee"><td><code>countBy...</code></td>
- * <td><code>long</code>, <code>Long</code>,
- * <br><code>int</code>, <code>Integer</code>,
- * <br><code>short</code>, <code>Short</code>,
- * <br><code>Number</code></td>
+ * <td><code>long</code>,
+ * <br><code>int</code></td>
  * <td>Jakarta Persistence providers limit the maximum to <code>Integer.MAX_VALUE</code></td></tr>
  *
  * <tr style="vertical-align: top"><td><code>deleteBy...</code>,
  * <br><code>updateBy...</code></td>
- * <td><code>void</code>, <code>Void</code>,
- * <br><code>boolean</code>, <code>Boolean</code>,
- * <br><code>long</code>, <code>Long</code>,
- * <br><code>int</code>, <code>Integer</code>,
- * <br><code>short</code>, <code>Short</code>,
- * <br><code>Number</code></td>
+ * <td><code>void</code>,
+ * <br><code>boolean</code>,
+ * <br><code>long</code>,
+ * <br><code>int</code></td>
  * <td>Jakarta Persistence providers limit the maximum to <code>Integer.MAX_VALUE</code></td></tr>
  *
  * <tr style="vertical-align: top; background-color:#eee"><td><code>existsBy...</code></td>
- * <td><code>boolean</code>, <code>Boolean</code></td>
+ * <td><code>boolean</code></td>
  * <td>For determining existence.</td></tr>
  *
  * <tr style="vertical-align: top"><td><code>find...By...</code></td>
@@ -525,29 +521,19 @@
  *
  * <tr style="vertical-align: top; background-color:#eee"><td><code>find...By...</code></td>
  * <td><code>E[]</code>,
- * <br><code>Iterable&lt;E&gt;</code>,
- * <br><code>Streamable&lt;E&gt;</code>,
- * <br><code>Collection&lt;E&gt;</code></td>
+ * <br><code>List&lt;E&gt;</code></td>
  * <td>For queries where it is possible to return more than 1 item.</td></tr>
  *
  * <tr style="vertical-align: top"><td><code>find...By...</code></td>
  * <td><code>Stream&lt;E&gt;</code></td>
  * <td>The caller must arrange to {@link java.util.stream.BaseStream#close() close}
  * all streams that it obtains from repository methods.</td></tr>
  *
- * <tr style="vertical-align: top; background-color:#eee"><td><code>find...By...</code></td>
- * <td><code>Collection</code> subtypes</td>
- * <td>The subtype must have a public default constructor and support <code>addAll</code> or <code>add</code></td></tr>
- *
  * <tr style="vertical-align: top"><td><code>find...By...(..., PageRequest)</code></td>
  * <td><code>Page&lt;E&gt;</code>, <code>KeysetAwarePage&lt;E&gt;</code>,
  * <br><code>Slice&lt;E&gt;</code>, <code>KeysetAwareSlice&lt;E&gt;</code></td>
  * <td>For use with pagination</td></tr>
  *
- * <tr style="vertical-align: top; background-color:#eee"><td><code>find...By...</code></td>
- * <td><code>LinkedHashMap&lt;K, E&gt;</code></td>
- * <td>Ordered map of Id attribute value to entity</td></tr>
- *
  * </table>
  *
  * <h3>Return Types for Annotated Methods</h3>