Polishing.

See #2878
Original pull request #2885

Author: schauder

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/CollectionUtils.java

@@ -30,7 +30,7 @@ class CollectionUtils {
 	 * @param count the number of first elements to be included in the returned list.
 	 * @param list must not be {@literal null}
 	 * @return the returned sublist if the {@code list} is greater {@code count}.
-	 * @param <T>
+	 * @param <T> the element type of the lists.
 	 */
 	public static <T> List<T> getFirst(int count, List<T> list) {
 
@@ -47,7 +47,7 @@ public static <T> List<T> getFirst(int count, List<T> list) {
 	 * @param count the number of last elements to be included in the returned list.
 	 * @param list must not be {@literal null}
 	 * @return the returned sublist if the {@code list} is greater {@code count}.
-	 * @param <T>
+	 * @param <T> the element type of the lists.
 	 */
 	public static <T> List<T> getLast(int count, List<T> list) {
 

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpaKeysetScrollQueryCreator.java

@@ -45,7 +45,9 @@ class JpaKeysetScrollQueryCreator extends JpaQueryCreator {
 	public JpaKeysetScrollQueryCreator(PartTree tree, ReturnedType type, CriteriaBuilder builder,
 			ParameterMetadataProvider provider, JpaEntityInformation<?, ?> entityInformation,
 			KeysetScrollPosition scrollPosition) {
+
 		super(tree, type, builder, provider);
+
 		this.entityInformation = entityInformation;
 		this.scrollPosition = scrollPosition;
 	}

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpaQueryExecution.java

@@ -142,6 +142,7 @@ static class ScrollExecution extends JpaQueryExecution {
 		private final ScrollDelegate<?> delegate;
 
 		ScrollExecution(Sort sort, ScrollDelegate<?> delegate) {
+
 			this.sort = sort;
 			this.delegate = delegate;
 		}

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/KeysetScrollDelegate.java

@@ -40,8 +40,8 @@ public class KeysetScrollDelegate {
 	/**
 	 * Factory method to obtain the right {@link KeysetScrollDelegate}.
 	 *
-	 * @param direction
-	 * @return
+	 * @param direction the direction of scrolling.
+	 * @return a {@link KeysetScrollDelegate} matching the requested direction.
 	 */
 	public static KeysetScrollDelegate of(Direction direction) {
 		return direction == Direction.Forward ? forward : reverse;
@@ -104,7 +104,6 @@ protected Sort getSortOrders(Sort sort) {
 		return sort;
 	}
 
-	@SuppressWarnings("unchecked")
 	protected <T> List<T> postProcessResults(List<T> result) {
 		return result;
 	}
@@ -154,7 +153,6 @@ public interface QueryStrategy<E, P> {
 		 * Create an expression object from the given {@code property} path.
 		 *
 		 * @param property must not be {@literal null}.
-		 * @return
 		 */
 		E createExpression(String property);
 
@@ -163,33 +161,33 @@ public interface QueryStrategy<E, P> {
 		 *
 		 * @param order must not be {@literal null}.
 		 * @param propertyExpression must not be {@literal null}.
-		 * @param value
-		 * @return
+		 * @param value the value to compare with. Must not be {@literal null}.
+		 * @return an object representing the comparison predicate.
 		 */
 		P compare(Order order, E propertyExpression, Object value);
 
 		/**
 		 * Create an equals-comparison object.
 		 *
 		 * @param propertyExpression must not be {@literal null}.
-		 * @param value
-		 * @return
+		 * @param value the value to compare with. Must not be {@literal null}.
+		 * @return an object representing the comparison predicate.
 		 */
 		P compare(E propertyExpression, @Nullable Object value);
 
 		/**
 		 * AND-combine the {@code intermediate} predicates.
 		 *
-		 * @param intermediate
-		 * @return
+		 * @param intermediate the predicates to combine. Must not be {@literal null}.
+		 * @return a single predicate.
 		 */
 		P and(List<P> intermediate);
 
 		/**
 		 * OR-combine the {@code intermediate} predicates.
 		 *
-		 * @param intermediate
-		 * @return
+		 * @param intermediate the predicates to combine. Must not be {@literal null}.
+		 * @return a single predicate.
 		 */
 		P or(List<P> intermediate);
 	}

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/KeysetScrollSpecification.java

@@ -56,7 +56,6 @@ public KeysetScrollSpecification(KeysetScrollPosition position, Sort sort, JpaEn
 	 * @param position must not be {@literal null}.
 	 * @param sort must not be {@literal null}.
 	 * @param entity must not be {@literal null}.
-	 * @return
 	 */
 	public static Sort createSort(KeysetScrollPosition position, Sort sort, JpaEntityInformation<?, ?> entity) {
 

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/NamedQuery.java

@@ -49,7 +49,6 @@ final class NamedQuery extends AbstractJpaQuery {
 	private final String queryName;
 	private final String countQueryName;
 	private final @Nullable String countProjection;
-	private final QueryExtractor extractor;
 	private final boolean namedCountQueryIsPresent;
 	private final DeclaredQuery declaredQuery;
 	private final QueryParameterSetter.QueryMetadataCache metadataCache;
@@ -63,7 +62,7 @@ private NamedQuery(JpaQueryMethod method, EntityManager em) {
 
 		this.queryName = method.getNamedQueryName();
 		this.countQueryName = method.getNamedCountQueryName();
-		this.extractor = method.getQueryExtractor();
+		QueryExtractor extractor = method.getQueryExtractor();
 		this.countProjection = method.getCountQueryProjection();
 
 		Parameters<?, ?> parameters = method.getParameters();
@@ -81,7 +80,7 @@ private NamedQuery(JpaQueryMethod method, EntityManager em) {
 		this.declaredQuery = DeclaredQuery.of(queryString, false);
 
 		boolean weNeedToCreateCountQuery = !namedCountQueryIsPresent && method.getParameters().hasPageableParameter();
-		boolean cantExtractQuery = !this.extractor.canExtractQuery();
+		boolean cantExtractQuery = !extractor.canExtractQuery();
 
 		if (weNeedToCreateCountQuery && cantExtractQuery) {
 			throw QueryCreationException.create(method, CANNOT_EXTRACT_QUERY);
@@ -99,9 +98,8 @@ private NamedQuery(JpaQueryMethod method, EntityManager em) {
 	/**
 	 * Returns whether the named query with the given name exists.
 	 *
-	 * @param em must not be {@literal null}.
+	 * @param em        must not be {@literal null}.
 	 * @param queryName must not be {@literal null}.
-	 * @return
 	 */
 	static boolean hasNamedQuery(EntityManager em, String queryName) {
 
@@ -129,8 +127,7 @@ static boolean hasNamedQuery(EntityManager em, String queryName) {
 	 * Looks up a named query for the given {@link org.springframework.data.repository.query.QueryMethod}.
 	 *
 	 * @param method must not be {@literal null}.
-	 * @param em must not be {@literal null}.
-	 * @return
+	 * @param em     must not be {@literal null}.
 	 */
 	@Nullable
 	public static RepositoryQuery lookupFrom(JpaQueryMethod method, EntityManager em) {

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/FetchableFluentQueryByPredicate.java

@@ -233,9 +233,9 @@ private Function<Object, R> getConversionFunction() {
 
 	static class PredicateScrollDelegate<T> extends ScrollDelegate<T> {
 
-		private final ScrollQueryFactory<T> scrollFunction;
+		private final ScrollQueryFactory scrollFunction;
 
-		PredicateScrollDelegate(ScrollQueryFactory<T> scrollQueryFactory, JpaEntityInformation<T, ?> entity) {
+		PredicateScrollDelegate(ScrollQueryFactory scrollQueryFactory, JpaEntityInformation<T, ?> entity) {
 			super(entity);
 			this.scrollFunction = scrollQueryFactory;
 		}

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/FetchableFluentQueryBySpecification.java

@@ -224,9 +224,9 @@ private Function<Object, R> getConversionFunction() {
 
 	static class SpecificationScrollDelegate<T> extends ScrollDelegate<T> {
 
-		private final ScrollQueryFactory<T> scrollFunction;
+		private final ScrollQueryFactory scrollFunction;
 
-		SpecificationScrollDelegate(ScrollQueryFactory<T> scrollQueryFactory, JpaEntityInformation<T, ?> entity) {
+		SpecificationScrollDelegate(ScrollQueryFactory scrollQueryFactory, JpaEntityInformation<T, ?> entity) {
 			super(entity);
 			this.scrollFunction = scrollQueryFactory;
 		}

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/FluentQuerySupport.java

@@ -86,7 +86,7 @@ final Function<Object, R> getConversionFunction(Class<S> inputType, Class<R> tar
 		return o -> DefaultConversionService.getSharedInstance().convert(o, targetType);
 	}
 
-	interface ScrollQueryFactory<T> {
+	interface ScrollQueryFactory {
 		Query createQuery(Sort sort, ScrollPosition scrollPosition);
 	}
 

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/JpaEntityInformation.java

@@ -35,8 +35,6 @@ public interface JpaEntityInformation<T, ID> extends EntityInformation<T, ID>, J
 
 	/**
 	 * Returns the id attribute of the entity.
-	 *
-	 * @return
 	 */
 	@Nullable
 	SingularAttribute<? super T, ?> getIdAttribute();
@@ -62,35 +60,30 @@ public interface JpaEntityInformation<T, ID> extends EntityInformation<T, ID>, J
 
 	/**
 	 * Returns {@literal true} if the entity has a composite id.
-	 *
-	 * @return
 	 */
 	boolean hasCompositeId();
 
 	/**
 	 * Returns the attribute names of the id attributes. If the entity has a composite id, then all id attribute names are
 	 * returned. If the entity has a single id attribute then this single attribute name is returned.
-	 *
-	 * @return
 	 */
 	Collection<String> getIdAttributeNames();
 
 	/**
 	 * Extracts the value for the given id attribute from a composite id
 	 *
-	 * @param id
-	 * @param idAttribute
-	 * @return
+	 * @param id the composite id from which to extract the attribute.
+	 * @param idAttribute the attribute name to extract.
 	 */
 	@Nullable
 	Object getCompositeIdAttributeValue(Object id, String idAttribute);
 
 	/**
 	 * Extract a keyset for {@code propertyPaths} and the primary key (including composite key components if applicable).
 	 *
-	 * @param propertyPaths
-	 * @param entity
-	 * @return
+	 * @param propertyPaths the property paths that make up the keyset in combination with the composite key components.
+	 * @param entity the entity to extract values from
+	 * @return a map mapping String representations of the paths to values from the entity.
 	 * @since 3.1
 	 */
 	Map<String, Object> getKeyset(Iterable<String> propertyPaths, T entity);

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/JpaMetamodelEntityInformation.java

@@ -85,12 +85,10 @@ public JpaMetamodelEntityInformation(Class<T> domainClass, Metamodel metamodel,
 
 		this.entityName = type instanceof EntityType ? ((EntityType<?>) type).getName() : null;
 
-		if (!(type instanceof IdentifiableType)) {
+		if (!(type instanceof IdentifiableType<T> identifiableType)) {
 			throw new IllegalArgumentException("The given domain class does not contain an id attribute");
 		}
 
-		IdentifiableType<T> identifiableType = (IdentifiableType<T>) type;
-
 		this.idMetadata = new IdMetadata<>(identifiableType, PersistenceProvider.fromMetamodel(metamodel));
 		this.versionAttribute = findVersionAttribute(identifiableType, metamodel);
 
@@ -108,7 +106,6 @@ public String getEntityName() {
 	 *
 	 * @param type must not be {@literal null}.
 	 * @param metamodel must not be {@literal null}.
-	 * @return
 	 */
 	@SuppressWarnings("unchecked")
 	private static <T> Optional<SingularAttribute<? super T, ?>> findVersionAttribute(IdentifiableType<T> type,
@@ -262,7 +259,6 @@ private static class IdMetadata<T> implements Iterable<SingularAttribute<? super
 		private final Set<SingularAttribute<? super T, ?>> attributes;
 		private @Nullable Class<?> idType;
 
-		@SuppressWarnings("unchecked")
 		IdMetadata(IdentifiableType<T> source, PersistenceProvider persistenceProvider) {
 
 			this.type = source;

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/Querydsl.java

@@ -73,8 +73,6 @@ public Querydsl(EntityManager em, PathBuilder<?> builder) {
 
 	/**
 	 * Creates the {@link JPQLQuery} instance based on the configured {@link EntityManager}.
-	 *
-	 * @return
 	 */
 	public <T> AbstractJPAQuery<T, JPAQuery<T>> createQuery() {
 
@@ -93,7 +91,6 @@ public <T> AbstractJPAQuery<T, JPAQuery<T>> createQuery() {
 	 * Creates the {@link JPQLQuery} instance based on the configured {@link EntityManager}.
 	 *
 	 * @param paths must not be {@literal null}.
-	 * @return
 	 */
 	public AbstractJPAQuery<Object, JPAQuery<Object>> createQuery(EntityPath<?>... paths) {
 
@@ -167,7 +164,6 @@ private <T> JPQLQuery<T> addOrderByFrom(QSort qsort, JPQLQuery<T> query) {
 	 *
 	 * @param sort must not be {@literal null}.
 	 * @param query must not be {@literal null}.
-	 * @return
 	 */
 	private <T> JPQLQuery<T> addOrderByFrom(Sort sort, JPQLQuery<T> query) {
 
@@ -185,7 +181,6 @@ private <T> JPQLQuery<T> addOrderByFrom(Sort sort, JPQLQuery<T> query) {
 	 * Transforms a plain {@link Order} into a QueryDsl specific {@link OrderSpecifier}.
 	 *
 	 * @param order must not be {@literal null}.
-	 * @return
 	 */
 	@SuppressWarnings({ "rawtypes", "unchecked" })
 	private OrderSpecifier<?> toOrderSpecifier(Order order) {
@@ -200,7 +195,6 @@ private OrderSpecifier<?> toOrderSpecifier(Order order) {
 	 * {@link NullHandling}.
 	 *
 	 * @param nullHandling must not be {@literal null}.
-	 * @return
 	 * @since 1.6
 	 */
 	private NullHandling toQueryDslNullHandling(org.springframework.data.domain.Sort.NullHandling nullHandling) {
@@ -225,7 +219,6 @@ private NullHandling toQueryDslNullHandling(org.springframework.data.domain.Sort
 	 * Creates an {@link Expression} for the given {@link Order} property.
 	 *
 	 * @param order must not be {@literal null}.
-	 * @return
 	 */
 	private Expression<?> buildOrderPropertyPathFrom(Order order) {
 
@@ -250,7 +243,6 @@ private Expression<?> buildOrderPropertyPathFrom(Order order) {
 	 * Creates an {@link Expression} for the given {@code property} property.
 	 *
 	 * @param property must not be {@literal null}.
-	 * @return
 	 */
 	Expression<?> createExpression(String property) {
 

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/QuerydslJpaPredicateExecutor.java

@@ -175,7 +175,7 @@ public <S extends T, R> R findBy(Predicate predicate, Function<FetchableFluentQu
 			return select;
 		};
 
-		ScrollQueryFactory<T> scroll = (sort, scrollPosition) -> {
+		ScrollQueryFactory scroll = (sort, scrollPosition) -> {
 
 			Predicate predicateToUse = predicate;
 

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/support/SimpleJpaRepository.java

@@ -521,7 +521,7 @@ private <S extends T, R> R doFindBy(Specification<T> spec, Class<T> domainClass,
 		Assert.notNull(spec, "Specification must not be null");
 		Assert.notNull(queryFunction, "Query function must not be null");
 
-		ScrollQueryFactory<T> scrollFunction = (sort, scrollPosition) -> {
+		ScrollQueryFactory scrollFunction = (sort, scrollPosition) -> {
 
 			Specification<T> specToUse = spec;
 

spring-data-jpa/src/test/java/org/springframework/data/jpa/domain/sample/Item.java

@@ -50,6 +50,7 @@ public Item(Integer id, Integer manufacturerId) {
 	}
 
 	public Item(Integer id, Integer manufacturerId, String name) {
+
 		this.id = id;
 		this.manufacturerId = manufacturerId;
 		this.name = name;