DATAJPA-1485 - Clarified documentation for @Modifying.

src/main/asciidoc/jpa.adoc

@@ -430,7 +430,9 @@ In the preceding example, the `MappedTypeRepository` interface is the common par
 [[jpa.modifying-queries]]
 === Modifying Queries
 
-All the previous sections describe how to declare queries to access a given entity or collection of entities. You can add custom modifying behavior by using the facilities described in "`<<repositories.custom-implementations>>`". As this approach is feasible for comprehensive custom functionality, you can modify queries that only need parameter binding by annotating the query method with `@Modifying`, as shown in the following example:
+All the previous sections describe how to declare queries to access a given entity or collection of entities.
+You can add custom modifying behavior by using the facilities described in "`<<repositories.custom-implementations>>`".
+As this approach is feasible for comprehensive custom functionality, you can modify queries that only need parameter binding by annotating the query method with `@Modifying`, as shown in the following example:
 
 .Declaring manipulating queries
 ====
@@ -442,7 +444,11 @@ int setFixedFirstnameFor(String firstname, String lastname);
 ----
 ====
 
-Doing so triggers the query annotated to the method as an updating query instead of a selecting one. As the `EntityManager` might contain outdated entities after the execution of the modifying query, we do not automatically clear it (see the https://docs.oracle.com/javaee/7/api/javax/persistence/EntityManager.html[JavaDoc] of `EntityManager.clear()` for details), since this effectively drops all non-flushed changes still pending in the `EntityManager`. If you wish the `EntityManager` to be cleared automatically, you can set the `@Modifying` annotation's `clearAutomatically` attribute to `true`.
+Doing so triggers the query annotated to the method as an updating query instead of a selecting one. As the `EntityManager` might contain outdated entities after the execution of the modifying query, we do not automatically clear it (see the https://docs.oracle.com/javaee/7/api/javax/persistence/EntityManager.html[JavaDoc] of `EntityManager.clear()` for details), since this effectively drops all non-flushed changes still pending in the `EntityManager`.
+If you wish the `EntityManager` to be cleared automatically, you can set the `@Modifying` annotation's `clearAutomatically` attribute to `true`.
+
+The `@Modifying` annotation is only relevant in combination with the `@Query` annotation.
+Derived query methods or custom methods do not require this Annotation.
 
 [[jpa.modifying-queries.derived-delete]]
 ==== Derived Delete Queries

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

@@ -22,11 +22,22 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Indicates a method should be regarded as modifying query.
+ * <p>
+ * Indicates a query method should be considered as modifying query as that changes the way it needs to be executed.
+ * This annotation is only considered if used on query methods defined through a {@link Query} annotation). It's not
+ * applied on custom implementation methods or queries derived from the method name as they already have control over
+ * the underlying data access APIs or specify if they are modifying by their name.
+ * </p>
+ * <p>
+ * Queries that require a `@Modifying` annotation include {@code INSERT}, {@code UPDATE}, {@code DELETE}, and DDL
+ * statements.
+ * </p>
  * 
  * @author Oliver Gierke
  * @author Christoph Strobl
  * @author Nicolas Cirigliano
+ * @author Jens Schauder
+ * @see Query
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
@@ -42,7 +53,7 @@ public @interface Modifying {
 
 	/**
 	 * Defines whether we should clear the underlying persistence context after executing the modifying query.
-	 * 
+	 *
 	 * @return
 	 */
 	boolean clearAutomatically() default false;

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

@@ -29,6 +29,8 @@ import org.springframework.data.annotation.QueryAnnotation;
  * @author Oliver Gierke
  * @author Thomas Darimont
  * @author Christoph Strobl
+ *
+ * @see Modifying
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })