Explicit notes on class/method-level semantics in class hierarchies

Issue: SPR-17445

(cherry picked from commit ea3250c8d6)

spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java

@@ -27,7 +27,12 @@ import org.springframework.core.annotation.AliasFor;
 import org.springframework.transaction.TransactionDefinition;
 
 /**
- * Describes transaction attributes on a method or class.
+ * Describes a transaction attribute on an individual method or on a class.
+ *
+ * <p>At the class level, this annotation applies as a default to all methods of
+ * the declaring class and its subclasses. Note that it does not apply to ancestor
+ * classes up the class hierarchy; methods need to be locally redeclared in order
+ * to participate in a subclass-level annotation.
  *
  * <p>This annotation type is generally directly comparable to Spring's
  * {@link org.springframework.transaction.interceptor.RuleBasedTransactionAttribute}

src/asciidoc/data-access.adoc

@@ -1090,6 +1090,12 @@ following class definition:
 	}
 ----
 
+Used at the class level as above, the annotation indicates a default for all methods
+of the declaring class (as well as its subclasses). Alternatively, each method can
+get annotated individually. Note that a class-level annotation does not apply to
+ancestor classes up the class hierarchy; in such a scenario, methods need to be
+locally redeclared in order to participate in a subclass-level annotation.
+
 When the above POJO is defined as a bean in a Spring IoC container, the bean instance
 can be made transactional by adding merely __one__ line of XML configuration:
 
@@ -1115,6 +1121,7 @@ can be made transactional by adding merely __one__ line of XML configuration:
 
 		<!-- enable the configuration of transactional behavior based on annotations -->
 		__<tx:annotation-driven transaction-manager="txManager"/>__<!-- a PlatformTransactionManager is still required -->
+
 		<bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
 			<!-- (this dependency is defined somewhere else) -->
 			<property name="dataSource" ref="dataSource"/>