Polishing.

Adding and correcting `@since` annotations.
Cleaning up some JavaDoc.
Tweaking some tests to make them more precise.

Original pull request #2148

Author: schauder

src/main/java/org/springframework/data/jpa/repository/JpaRepository.java

@@ -72,16 +72,17 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
 	/**
 	 * Saves an entity and flushes changes instantly.
 	 *
-	 * @param entity
+	 * @param entity entity to be saved. Must not be {@literal null}.
 	 * @return the saved entity
 	 */
 	<S extends T> S saveAndFlush(S entity);
 
 	/**
 	 * Saves all entities and flushes changes instantly.
 	 *
-	 * @param entities
+	 * @param entities entities to be deleted. Must not be {@literal null}.
 	 * @return the saved entities
+	 * @since 2.5
 	 */
 	<S extends T> List<S> saveAllAndFlush(Iterable<S> entities);
 
@@ -90,7 +91,7 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
 	 * first level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this
 	 * method.
 	 *
-	 * @param entities
+	 * @param entities entities to be deleted. Must not be {@literal null}.
 	 * @deprecated Use {@link #deleteAllInBatch(Iterable)} instead.
 	 */
 	@Deprecated
@@ -101,8 +102,8 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
 	 * first level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this
 	 * method.
 	 *
-	 * @param entities
-	 * @since 3.0
+	 * @param entities entities to be deleted. Must not be {@literal null}.
+	 * @since 2.5
 	 */
 	void deleteAllInBatch(Iterable<T> entities);
 
@@ -111,8 +112,8 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
 	 * Deletes the entities identified by the given ids using a single query. This kind of operation leaves JPAs first
 	 * level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this method.
 	 *
-	 * @param ids
-	 * @since 3.0
+	 * @param ids the ids of the entities to be deleted. Must not be {@literal null}.
+	 * @since 2.5
 	 */
 	void deleteAllByIdInBatch(Iterable<ID> ids);
 

src/test/java/org/springframework/data/jpa/repository/UserRepositoryTests.java

@@ -46,7 +46,6 @@
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
-
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.dao.DataAccessException;
 import org.springframework.dao.DataIntegrityViolationException;
@@ -60,16 +59,16 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.domain.ExampleMatcher.*;
 import org.springframework.data.domain.Sort.Direction;
 import org.springframework.data.domain.Sort.Order;
-import org.springframework.data.domain.ExampleMatcher.*;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.data.jpa.domain.sample.Address;
 import org.springframework.data.jpa.domain.sample.Role;
 import org.springframework.data.jpa.domain.sample.SpecialUser;
 import org.springframework.data.jpa.domain.sample.User;
-import org.springframework.data.jpa.repository.sample.SampleEvaluationContextExtension.SampleSecurityContextHolder;
 import org.springframework.data.jpa.repository.sample.UserRepository;
+import org.springframework.data.jpa.repository.sample.SampleEvaluationContextExtension.SampleSecurityContextHolder;
 import org.springframework.data.jpa.repository.sample.UserRepository.NameOnly;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
@@ -152,8 +151,8 @@ void findsAllByGivenIds() {
 
 		flushTestUsers();
 
-		assertThat(repository.findAllById(asList(firstUser.getId(), secondUser.getId()))).contains(firstUser,
-				secondUser);
+		assertThat(repository.findAllById(asList(firstUser.getId(), secondUser.getId()))) //
+				.containsExactlyInAnyOrder(firstUser, secondUser);
 	}
 
 	@Test
@@ -167,23 +166,23 @@ void testReadByIdReturnsNullForNotFoundEntities() {
 	@Test
 	void savesCollectionCorrectly() throws Exception {
 
-		assertThat(repository.saveAll(asList(firstUser, secondUser, thirdUser))).hasSize(3).contains(firstUser,
-				secondUser, thirdUser);
+		assertThat(repository.saveAll(asList(firstUser, secondUser, thirdUser))) //
+				.containsExactlyInAnyOrder(firstUser, secondUser, thirdUser);
 	}
 
-	@Test // DATAJPA-1574
+	@Test // gh-2148
 	void savesAndFlushesCollectionCorrectly() {
 
-		assertThat(repository.saveAllAndFlush(asList(firstUser, secondUser, thirdUser))).hasSize(3).contains(firstUser,
-				secondUser, thirdUser);
+		assertThat(repository.saveAllAndFlush(asList(firstUser, secondUser, thirdUser))) //
+				.containsExactlyInAnyOrder(firstUser, secondUser, thirdUser);
 	}
 
 	@Test
 	void savingEmptyCollectionIsNoOp() throws Exception {
 		assertThat(repository.saveAll(new ArrayList<>())).isEmpty();
 	}
 
-	@Test // DATAJPA-1574
+	@Test // gh-2148
 	void savingAndFlushingEmptyCollectionIsNoOp() {
 		assertThat(repository.saveAllAndFlush(new ArrayList<>())).isEmpty();
 	}
@@ -1114,7 +1113,7 @@ void saveAndFlushShouldSupportReturningSubTypesOfRepositoryEntity() {
 		assertThat(user.getEmailAddress()).isEqualTo(savedUser.getEmailAddress());
 	}
 
-	@Test // DATAJPA-1574
+	@Test // gh-2148
 	void saveAllAndFlushShouldSupportReturningSubTypesOfRepositoryEntity() {
 
 		repository.deleteAll();