DATACMNS-928 - Polishing.

Additional JavaDoc and @since tags. Minor additions to AbstractAggregateRoot.

src/main/java/org/springframework/data/domain/AbstractAggregateRoot.java

@@ -20,19 +20,43 @@ import lombok.Getter;
 import java.util.ArrayList;
 import java.util.List;
 
+import org.springframework.util.Assert;
+
 /**
+ * Convenience base class for aggregate roots that exposes a {@link #registerEvent(Object)} to capture domain events and
+ * expose them via {@link #getDomainEvents()}. The implementation is using the general event publication mechanism
+ * implied by {@link DomainEvents} and {@link AfterDomainEventPublication}. If in doubt or need to customize anything
+ * here, rather build your own base class and use the annotations directly.
+ * 
  * @author Oliver Gierke
+ * @since 1.13
  */
 public class AbstractAggregateRoot {
 
-	private transient final @Getter(onMethod = @__(@DomainEvents)) List<Object> domainEvents = new ArrayList<Object>();
+	/**
+	 * All domain events currently captured by the aggregate.
+	 */
+	@Getter(onMethod = @__(@DomainEvents)) //
+	private transient final List<Object> domainEvents = new ArrayList<Object>();
 
+	/**
+	 * Registers the given event object for publication on a call to a Spring Data repository's save method.
+	 * 
+	 * @param event must not be {@literal null}.
+	 * @return
+	 */
 	protected <T> T registerEvent(T event) {
 
+		Assert.notNull(event, "Domain event must not be null!");
+
 		this.domainEvents.add(event);
 		return event;
 	}
 
+	/**
+	 * Clears all domain events currently held. Usually invoked by the infrastructure in place in Spring Data
+	 * repositories.
+	 */
 	@AfterDomainEventPublication
 	public void clearDomainEvents() {
 		this.domainEvents.clear();

src/main/java/org/springframework/data/domain/AfterDomainEventPublication.java

@@ -26,6 +26,7 @@ import java.lang.annotation.Target;
  * 
  * @author Oliver Gierke
  * @see DomainEvents
+ * @since 1.13
  * @soundtrack Benny Greb - September (Moving Parts Live)
  */
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/org/springframework/data/domain/DomainEvents.java

@@ -29,6 +29,7 @@ import org.springframework.context.ApplicationEventPublisher;
  * @author Oliver Gierke
  * @see ApplicationEventPublisher
  * @see AfterDomainEventPublication
+ * @since 1.13
  * @soundtrack Benny Greb - Soulfood (Moving Parts Live)
  */
 @Retention(RetentionPolicy.RUNTIME)