Improve documentation for deleteById.

The documentation now clarifies that entity might get loaded and therefore possibly OptimisticLockingFailureException might get thrown.

Closes #3280

Author: schauder

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-commons</artifactId>
-	<version>3.5.0-SNAPSHOT</version>
+	<version>3.5.0-repository-optimistic-locking-SNAPSHOT</version>
 
 	<name>Spring Data Core</name>
 	<description>Core Spring concepts underpinning every Spring Data module.</description>

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

@@ -20,8 +20,11 @@
 import org.springframework.dao.OptimisticLockingFailureException;
 
 /**
- * Interface for generic CRUD operations on a repository for a specific type.
- *
+ * 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.
+ * 
  * @author Oliver Gierke
  * @author Eberhard Wolff
  * @author Jens Schauder
@@ -106,7 +109,11 @@ 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}
 	 */