Polishing.

Align documentation between reactive and imperative repository variants.

See #3280
Original pull request: #3281

src/main/java/org/springframework/data/repository/CrudRepository.java

@@ -20,11 +20,11 @@ import java.util.Optional;
 import org.springframework.dao.OptimisticLockingFailureException;
 
 /**
- * Interface for generic CRUD operations on a repository for a specific type. In general operations offered via this
- * interface participate in life cycle events, and optimistic locking. Therefore, modules may choose to load an entity
- * before deleting or updating it in order to facilitate this, and any modifying method call may trigger an exception
- * due to failure of optimistic locking.
- * 
+ * Interface for generic CRUD operations on a repository for a specific type. Methods exposed through this interface
+ * allow entities to participate in lifecycle events, and optimistic locking if applicable except for some bulk
+ * operation methods. Therefore, modules may choose to load an entity before deleting or updating it in order to
+ * facilitate events, and any modifying method call may trigger an exception due to failure of optimistic locking.
+ *
  * @author Oliver Gierke
  * @author Eberhard Wolff
  * @author Jens Schauder
@@ -109,13 +109,12 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 * Deletes the entity with the given id.
 	 * <p>
 	 * If the entity is not found in the persistence store it is silently ignored.
-	 * <p>
-	 * Note that, since this method triggers life cycle events, it might need to load an entity before deleting it. This
-	 * also might trigger {@link OptimisticLockingFailureException} if between loading and actually deleting the entity,
-	 * the entity was changed by some other process.
-	 * 
+	 *
 	 * @param id must not be {@literal null}.
 	 * @throws IllegalArgumentException in case the given {@literal id} is {@literal null}
+	 * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with
+	 *           a different value from that found in the persistence store. Also thrown if the entity is assumed to be
+	 *           present but does not exist in the database.
 	 */
 	void deleteById(ID id);
 
@@ -137,6 +136,9 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 *
 	 * @param ids must not be {@literal null}. Must not contain {@literal null} elements.
 	 * @throws IllegalArgumentException in case the given {@literal ids} or one of its elements is {@literal null}.
+	 * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with
+	 *           a different value from that found in the persistence store. Also thrown if the entity is assumed to be
+	 *           present but does not exist in the database.
 	 * @since 2.5
 	 */
 	void deleteAllById(Iterable<? extends ID> ids);
@@ -156,4 +158,5 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 * Deletes all entities managed by the repository.
 	 */
 	void deleteAll();
+
 }

src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java

@@ -26,16 +26,17 @@ import org.springframework.data.repository.Repository;
 
 /**
  * Interface for generic CRUD operations on a repository for a specific type. This repository follows reactive paradigms
- * and uses Project Reactor types which are built on top of Reactive Streams.
+ * and uses Project Reactor types which are built on top of Reactive Streams. Methods exposed through this interface
+ * allow entities to participate in lifecycle events, and optimistic locking if applicable except for some bulk
+ * operation methods. Therefore, modules may choose to load an entity before deleting or updating it in order to
+ * facilitate events, and any modifying method call may trigger an exception due to failure of optimistic locking.
  * <p>
  * Save and delete operations with entities that have a version attribute trigger an {@code onError} with a
  * {@link org.springframework.dao.OptimisticLockingFailureException} when they encounter a different version value in
  * the persistence store than in the entity passed as an argument.
- * </p>
  * <p>
  * Other delete operations that only receive ids or entities without version attribute do not trigger an error when no
  * matching data is found in the persistence store.
- * </p>
  *
  * @author Mark Paluch
  * @author Christph Strobl

src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java

@@ -26,16 +26,17 @@ import org.springframework.data.repository.Repository;
 
 /**
  * Interface for generic CRUD operations on a repository for a specific type. This repository follows reactive paradigms
- * and uses RxJava 3 types.
+ * and uses RxJava 3 types. Methods exposed through this interface allow entities to participate in lifecycle events,
+ * and optimistic locking if applicable except for some bulk operation methods. Therefore, modules may choose to load an
+ * entity before deleting or updating it in order to facilitate events, and any modifying method call may trigger an
+ * exception due to failure of optimistic locking.
  * <p>
  * Save and delete operations with entities that have a version attribute trigger an {@code onError} with a
  * {@link org.springframework.dao.OptimisticLockingFailureException} when they encounter a different version value in
  * the persistence store than in the entity passed as an argument.
- * </p>
  * <p>
  * Other delete operations that only receive ids or entities without version attribute do not trigger an error when no
  * matching data is found in the persistence store.
- * </p>
  *
  * @author Mark Paluch
  * @since 2.4