From b54cd4e3915766a54ac260249847c233cc8958e0 Mon Sep 17 00:00:00 2001
From: Christoph Strobl <cstrobl@pivotal.io>
Date: Thu, 7 Feb 2019 14:53:16 +0100
Subject: [PATCH] DATAMONGO-2195 - Documentation update.

Original pull request: #641.
---
 .../data/mongodb/core/EntityOperations.java      | 10 ++++++----
 .../data/mongodb/core/MongoOperations.java       | 16 ++++++----------
 .../repository/query/MongoEntityInformation.java |  5 +++--
 3 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/EntityOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/EntityOperations.java
index cb7870d25..e990ce587 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/EntityOperations.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/EntityOperations.java
@@ -239,9 +239,11 @@ class EntityOperations {
 		}
 
 		/**
-		 * Returns the value of the version if the entity has a version property, {@literal null} otherwise.
+		 * Returns the value of the version if the entity {@link #isVersionedEntity() has a version property}.
 		 *
-		 * @return
+		 * @return the entity version. Can be {@literal null}.
+		 * @throws IllegalStateException if the entity does not define a {@literal version} property. Make sure to check
+		 *           {@link #isVersionedEntity()}.
 		 */
 		@Nullable
 		Object getVersion();
@@ -297,8 +299,8 @@ class EntityOperations {
 		/**
 		 * Returns the current version value if the entity has a version property.
 		 *
-		 * @return the current version or {@literal null} in case it's uninitialized or the entity doesn't expose a version
-		 *         property.
+		 * @return the current version or {@literal null} in case it's uninitialized.
+		 * @throws IllegalStateException if the entity does not define a {@literal version} property.
 		 */
 		@Nullable
 		Number getVersion();
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
index 89f693d15..85f3d411a 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
@@ -1351,28 +1351,24 @@ public interface MongoOperations extends FluentMongoOperations {
 
 	/**
 	 * Remove the given object from the collection by {@literal id} and (if applicable) its
-	 * {@link org.springframework.data.annotation.Version}.
+	 * {@link org.springframework.data.annotation.Version}. <br />
+	 * Use {@link DeleteResult#getDeletedCount()} for insight whether an {@link DeleteResult#wasAcknowledged()
+	 * acknowledged} remove operation was successful or not.
 	 *
 	 * @param object must not be {@literal null}.
 	 * @return the {@link DeleteResult} which lets you access the results of the previous delete.
-	 * @throws org.springframework.dao.OptimisticLockingFailureException if the given {@literal object} is
-	 *           {@link org.springframework.data.annotation.Version versioned} and the current version does not match the
-	 *           one within the store. If no document with matching {@literal _id} exists in the collection the operation
-	 *           completes without error.
 	 */
 	DeleteResult remove(Object object);
 
 	/**
 	 * Removes the given object from the given collection by {@literal id} and (if applicable) its
-	 * {@link org.springframework.data.annotation.Version}.
+	 * {@link org.springframework.data.annotation.Version}. <br />
+	 * Use {@link DeleteResult#getDeletedCount()} for insight whether an {@link DeleteResult#wasAcknowledged()
+	 * acknowledged} remove operation was successful or not.
 	 *
 	 * @param object must not be {@literal null}.
 	 * @param collectionName name of the collection where the objects will removed, must not be {@literal null} or empty.
 	 * @return the {@link DeleteResult} which lets you access the results of the previous delete.
-	 * @throws org.springframework.dao.OptimisticLockingFailureException if the given {@literal object} is
-	 *           {@link org.springframework.data.annotation.Version versioned} and the current version does not match the
-	 *           one within the store. If no document with matching {@literal _id} exists in the collection the operation
-	 *           completes without error.
 	 */
 	DeleteResult remove(Object object, String collectionName);
 
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoEntityInformation.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoEntityInformation.java
index e1f9ae8ee..c58732f58 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoEntityInformation.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/repository/query/MongoEntityInformation.java
@@ -43,7 +43,7 @@ public interface MongoEntityInformation<T, ID> extends EntityInformation<T, ID>
 	/**
 	 * Returns whether the entity uses optimistic locking.
 	 *
-	 * @return
+	 * @return true if the entity defines a {@link org.springframework.data.annotation.Version} property.
 	 * @since 2.2
 	 */
 	default boolean isVersioned() {
@@ -54,7 +54,8 @@ public interface MongoEntityInformation<T, ID> extends EntityInformation<T, ID>
 	 * Returns the version value for the entity or {@literal null} if the entity is not {@link #isVersioned() versioned}.
 	 *
 	 * @param entity must not be {@literal null}
-	 * @return
+	 * @return can be {@literal null}.
+	 * @since 2.2
 	 */
 	@Nullable
 	default Object getVersion(T entity) {