DATAMONGO-2195 - Documentation update.

Original pull request: #641.

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
+		 * @return the current version or {@literal null} in case it's uninitialized.
-		 *         property.
+		 * @throws IllegalStateException if the entity does not define a {@literal version} property.
 		 */
 		@Nullable
 		Number getVersion();

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);
 

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) {