Adding javadoc comments.

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/ValidationErrors.java

@@ -9,10 +9,11 @@ import org.springframework.validation.FieldError;
 import org.springframework.validation.ObjectError;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * An {@link Errors} implementation for use in the events mechanism of Spring Data REST.
+ *
+ * @author Jon Brisbin
  */
-public class ValidationErrors
-    extends AbstractErrors {
+public class ValidationErrors extends AbstractErrors {
 
   private String         name;
   private Object         entity;

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/AfterDeleteEvent.java

@@ -1,9 +1,9 @@
 package org.springframework.data.rest.repository.context;
 
 /**
- * Emitted after the entity is delete from the repository.
+ * Emitted after the entity is deleted from the repository.
  *
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * @author Jon Brisbin
  */
 public class AfterDeleteEvent
     extends RepositoryEvent {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/AfterLinkDeleteEvent.java

@@ -1,6 +1,8 @@
 package org.springframework.data.rest.repository.context;
 
 /**
+ * Emitted after a link to a related object is deleted from the parent.
+ *
  * @author Jon Brisbin
  */
 public class AfterLinkDeleteEvent extends LinkSaveEvent {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/AfterLinkSaveEvent.java

@@ -1,9 +1,9 @@
 package org.springframework.data.rest.repository.context;
 
 /**
- * Emitted immediately after saving a linked object to its parent in the repository.
+ * Emitted after saving a linked object to its parent in the repository.
  *
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * @author Jon Brisbin
  */
 public class AfterLinkSaveEvent
     extends LinkSaveEvent {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/AfterSaveEvent.java

@@ -1,9 +1,9 @@
 package org.springframework.data.rest.repository.context;
 
 /**
- * Emitted immediately after a save to the repository.
+ * Emitted after a save to the repository.
  *
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * @author Jon Brisbin
  */
 public class AfterSaveEvent
     extends RepositoryEvent {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/AnnotatedHandlerRepositoryEventListener.java

@@ -32,10 +32,9 @@ import org.springframework.util.ReflectionUtils;
  *
  * @author Jon Brisbin <jbrisbin@vmware.com>
  */
-public class AnnotatedHandlerRepositoryEventListener
-    implements ApplicationListener<RepositoryEvent>,
-               ApplicationContextAware,
-               InitializingBean {
+public class AnnotatedHandlerRepositoryEventListener implements ApplicationListener<RepositoryEvent>,
+                                                                ApplicationContextAware,
+                                                                InitializingBean {
 
   private String             basePackage;
   private ApplicationContext applicationContext;

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/BeforeLinkDeleteEvent.java

@@ -1,9 +1,11 @@
 package org.springframework.data.rest.repository.context;
 
 /**
+ * Emitted before a link to a related object is deleted from the parent.
+ *
  * @author Jon Brisbin
  */
-public class BeforeLinkDeleteEvent extends LinkSaveEvent{
+public class BeforeLinkDeleteEvent extends LinkSaveEvent {
   public BeforeLinkDeleteEvent(Object source, Object linked) {
     super(source, linked);
   }

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/LinkSaveEvent.java

@@ -1,9 +1,9 @@
 package org.springframework.data.rest.repository.context;
 
 /**
- * Base class for {@link RepositoryEvent}s that deal with saving a linked object.
+ * Base class for {@link RepositoryEvent}s that deal with saving/updating or deleting a linked object.
  *
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * @author Jon Brisbin
  */
 public abstract class LinkSaveEvent
     extends RepositoryEvent {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/context/RepositoryEvent.java

@@ -3,10 +3,11 @@ package org.springframework.data.rest.repository.context;
 import org.springframework.context.ApplicationEvent;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Abstract base class for events emitted by the REST exporter.
+ *
+ * @author Jon Brisbin
  */
-public abstract class RepositoryEvent
-    extends ApplicationEvent {
+public abstract class RepositoryEvent extends ApplicationEvent {
   protected RepositoryEvent(Object source) {
     super(source);
   }

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/invoke/CrudMethod.java

@@ -3,6 +3,9 @@ package org.springframework.data.rest.repository.invoke;
 import java.lang.reflect.Method;
 
 /**
+ * Represents one of the CRUD methods supported by {@link org.springframework.data.repository.PagingAndSortingRepository}
+ * or {@link org.springframework.data.repository.CrudRepository}.
+ *
  * @author Jon Brisbin
  */
 public enum CrudMethod {
@@ -17,6 +20,14 @@ public enum CrudMethod {
   SAVE_ONE,
   SAVE_SOME;
 
+  /**
+   * Get an enum from a {@link Method}. Narrow down overriden methods by looking for {@link Iterable} in the first
+   * parameter, which tells us it is a '_SOME' type.
+   *
+   * @param m
+   *
+   * @return
+   */
   public static CrudMethod fromMethod(Method m) {
     String s = m.getName();
     Class<?>[] paramTypes = m.getParameterTypes();
@@ -38,6 +49,11 @@ public enum CrudMethod {
     }
   }
 
+  /**
+   * Turn this enum into a method name.
+   *
+   * @return
+   */
   public String toMethodName() {
     switch(this) {
       case COUNT:

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/invoke/RepositoryMethodResponse.java

@@ -9,6 +9,9 @@ import org.codehaus.jackson.annotate.JsonProperty;
 import org.springframework.data.rest.core.Link;
 
 /**
+ * JSON-serializable response for returns that have a mix of results and links. Also used in responses that have just
+ * links (in that case, 'results' will be an empty array).
+ *
  * @author Jon Brisbin
  */
 public class RepositoryMethodResponse {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/invoke/RepositoryQueryMethod.java

@@ -9,6 +9,8 @@ import org.springframework.data.repository.query.Param;
 import org.springframework.util.Assert;
 
 /**
+ * Represents a query method on a repository interface.
+ *
  * @author Jon Brisbin <jbrisbin@vmware.com>
  */
 public class RepositoryQueryMethod {
@@ -49,14 +51,29 @@ public class RepositoryQueryMethod {
     }
   }
 
+  /**
+   * The method's parameter types.
+   *
+   * @return
+   */
   public Class<?>[] paramTypes() {
     return paramTypes;
   }
 
+  /**
+   * The parameter names as pulled from the {@link Param} annotations.
+   *
+   * @return
+   */
   public String[] paramNames() {
     return paramNames;
   }
 
+  /**
+   * The {@link Method} to invoke.
+   *
+   * @return
+   */
   public Method method() {
     return method;
   }

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/jpa/JpaAttributeMetadata.java

@@ -15,7 +15,9 @@ import org.springframework.data.rest.repository.AttributeMetadata;
 import org.springframework.util.ReflectionUtils;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Implementation of {@link AttributeMetadata} for JPA.
+ *
+ * @author Jon Brisbin
  */
 public class JpaAttributeMetadata implements AttributeMetadata {
 

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/jpa/JpaEntityMetadata.java

@@ -15,7 +15,9 @@ import org.springframework.util.ReflectionUtils;
 import org.springframework.util.StringUtils;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Implementation of {@link EntityMetadata} for JPA.
+ *
+ * @author Jon Brisbin
  */
 public class JpaEntityMetadata
     implements EntityMetadata<JpaAttributeMetadata> {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/jpa/JpaRepositoryExporter.java

@@ -10,7 +10,7 @@ import org.springframework.data.rest.repository.RepositoryExporter;
 /**
  * Implementation of {@link RepositoryExporter} for exporting JPA {@link Repository} subinterfaces.
  *
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * @author Jon Brisbin
  */
 public class JpaRepositoryExporter
     extends RepositoryExporter<JpaRepositoryMetadata, JpaEntityMetadata> {

spring-data-rest-repository/src/main/java/org/springframework/data/rest/repository/jpa/JpaRepositoryMetadata.java

@@ -20,7 +20,9 @@ import org.springframework.util.ReflectionUtils;
 import org.springframework.util.StringUtils;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Implementation of {@link RepositoryMetadata} for JPA.
+ *
+ * @author Jon Brisbin
  */
 public class JpaRepositoryMetadata implements RepositoryMetadata<JpaEntityMetadata> {
 

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/PagingAndSortingMethodArgumentResolver.java

@@ -17,6 +17,9 @@ import org.springframework.web.method.support.HandlerMethodArgumentResolver;
 import org.springframework.web.method.support.ModelAndViewContainer;
 
 /**
+ * {@link HandlerMethodArgumentResolver} implementation responsible for inspecting a request for page and sort
+ * parameters for use by the repositories.
+ *
  * @author Jon Brisbin
  */
 public class PagingAndSortingMethodArgumentResolver

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestConfiguration.java

@@ -8,6 +8,9 @@ import org.springframework.http.converter.HttpMessageConverter;
 import org.springframework.util.Assert;
 
 /**
+ * Central configuration helper class for the REST exporter. If something within the REST exporter is configurable,
+ * there is a property here you can use to set the value.
+ *
  * @author Jon Brisbin
  */
 public class RepositoryRestConfiguration {
@@ -24,87 +27,200 @@ public class RepositoryRestConfiguration {
   private MediaType                     defaultMediaType    = MediaType.APPLICATION_JSON;
   private boolean                       dumpErrors          = true;
 
+  /**
+   * Get the default size of {@link org.springframework.data.domain.Pageable}s. Default is 20.
+   *
+   * @return
+   */
   public int getDefaultPageSize() {
     return defaultPageSize;
   }
 
+  /**
+   * Set the default size of {@link org.springframework.data.domain.Pageable}s.
+   *
+   * @param defaultPageSize
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setDefaultPageSize(int defaultPageSize) {
     Assert.isTrue((defaultPageSize > 0), "Page size must be greater than 0.");
     this.defaultPageSize = defaultPageSize;
     return this;
   }
 
+  /**
+   * Get the name of the URL query string parameter that indicates what page to return. Default is 'page'.
+   *
+   * @return
+   */
   public String getPageParamName() {
     return pageParamName;
   }
 
+  /**
+   * Set the name of the URL query string parameter that indicates what page to return.
+   *
+   * @param pageParamName
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setPageParamName(String pageParamName) {
     Assert.notNull(pageParamName, "Page param name cannot be null.");
     this.pageParamName = pageParamName;
     return this;
   }
 
+  /**
+   * Get the name of the URL query string parameter that indicates how many results to return at once. Default is
+   * 'limit'.
+   *
+   * @return
+   */
   public String getLimitParamName() {
     return limitParamName;
   }
 
+  /**
+   * Set the name of the URL query string parameter that indicates how many results to return at once.
+   *
+   * @param limitParamName
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setLimitParamName(String limitParamName) {
     Assert.notNull(limitParamName, "Limit param name cannot be null.");
     this.limitParamName = limitParamName;
     return this;
   }
 
+  /**
+   * Get the name of the URL query string parameter that indicates what direction to sort results. Default is 'sort'.
+   *
+   * @return
+   */
   public String getSortParamName() {
     return sortParamName;
   }
 
+  /**
+   * Set the name of the URL query string parameter that indicates what direction to sort results.
+   *
+   * @param sortParamName
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setSortParamName(String sortParamName) {
     Assert.notNull(sortParamName, "Sort param name cannot be null.");
     this.sortParamName = sortParamName;
     return this;
   }
 
+  /**
+   * Get the list of custom {@link HttpMessageConverter}s to be used to convert user input to objects and visa versa.
+   *
+   * @return
+   */
   public List<HttpMessageConverter<?>> getCustomConverters() {
     return customConverters;
   }
 
+  /**
+   * Set the list of custom {@link HttpMessageConverter}s to be used to convert user input to objects and visa versa.
+   *
+   * @param customConverters
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setCustomConverters(List<HttpMessageConverter<?>> customConverters) {
     Assert.notNull(customConverters, "Custom converters list cannot be null.");
     this.customConverters = customConverters;
     return this;
   }
 
+  /**
+   * Get the name of the URL query string parameter that indicates the name of the javascript function to use as the
+   * JSONP wrapper for results.
+   *
+   * @return
+   */
   public String getJsonpParamName() {
     return jsonpParamName;
   }
 
+  /**
+   * Set the name of the URL query string parameter that indicates the name of the javascript function to use as the
+   * JSONP wrapper for results.
+   *
+   * @param jsonpParamName
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setJsonpParamName(String jsonpParamName) {
     this.jsonpParamName = jsonpParamName;
     return this;
   }
 
+  /**
+   * Get the name of the URL query string parameter that indicates the name of the javascript function to use as the
+   * error handler JSONP wrapper for errors.
+   *
+   * @return
+   */
   public String getJsonpOnErrParamName() {
     return jsonpOnErrParamName;
   }
 
+  /**
+   * Set the name of the URL query string parameter that indicates the name of the javascript function to use as the
+   * error handler JSONP wrapper for errors.
+   *
+   * @param jsonpOnErrParamName
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setJsonpOnErrParamName(String jsonpOnErrParamName) {
     this.jsonpOnErrParamName = jsonpOnErrParamName;
     return this;
   }
 
+  /**
+   * Get the {@link MediaType} to use as a default when none is specified.
+   *
+   * @return
+   */
   public MediaType getDefaultMediaType() {
     return defaultMediaType;
   }
 
+  /**
+   * Set the {@link MediaType} to use as a default when none is specified.
+   *
+   * @param defaultMediaType
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setDefaultMediaType(MediaType defaultMediaType) {
     this.defaultMediaType = defaultMediaType;
     return this;
   }
 
+  /**
+   * Should exception messages be logged to the body of the response in a JSON object?
+   *
+   * @return
+   */
   public boolean isDumpErrors() {
     return dumpErrors;
   }
 
+  /**
+   * Set whether exception messages should be logged to the body of the response as a JSON object.
+   *
+   * @param dumpErrors
+   *
+   * @return
+   */
   public RepositoryRestConfiguration setDumpErrors(boolean dumpErrors) {
     this.dumpErrors = dumpErrors;
     return this;

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestExporterServlet.java

@@ -5,7 +5,10 @@ import org.springframework.web.context.support.AnnotationConfigWebApplicationCon
 import org.springframework.web.servlet.DispatcherServlet;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Convenience {@link DispatcherServlet} that sets the 'contextClass' and 'contextConfigLocation' properties to the
+ * correct values for using the REST exporter in a web.xml file.
+ *
+ * @author Jon Brisbin
  */
 public class RepositoryRestExporterServlet extends DispatcherServlet {
 

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestHandlerAdapter.java

@@ -7,6 +7,11 @@ import org.springframework.web.method.HandlerMethod;
 import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter;
 
 /**
+ * {@link RequestMappingHandlerAdapter} implementation that adds a couple argument resolvers for controller method
+ * parameters used in the REST exporter controller. Also only looks for handler methods in the {@link
+ * RepositoryRestController} class to help isolate this handler adapter from other handler adapters the user might have
+ * configured in their Spring MVC context.
+ *
  * @author Jon Brisbin
  */
 public class RepositoryRestHandlerAdapter extends RequestMappingHandlerAdapter {

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestHandlerMapping.java

@@ -15,6 +15,11 @@ import org.springframework.web.method.HandlerMethod;
 import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
 
 /**
+ * {@link RequestMappingHandlerMapping} implementation that will only find a handler method if a {@link
+ * org.springframework.data.repository.Repository} is exported under that URL path segment. Also ensures the {@link
+ * OpenEntityManagerInViewInterceptor} is registered in the application context. The OEMIVI is required for the REST
+ * exporter to function properly.
+ *
  * @author Jon Brisbin
  */
 public class RepositoryRestHandlerMapping extends RequestMappingHandlerMapping {

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestMvcConfiguration.java

@@ -13,25 +13,52 @@ import org.springframework.web.method.support.HandlerMethodArgumentResolver;
 import org.springframework.web.servlet.mvc.method.annotation.ExceptionHandlerExceptionResolver;
 
 /**
- * @author Jon Brisbin <jbrisbin@vmware.com>
+ * Main Spring MVC configuration for the REST exporter. Can be subclassed and any of these methods overridden to
+ * provide
+ * custom configuration for your environment. More than likely, however, it won't be necessary to do this as most
+ * user-configurable properties are defined on the {@link RepositoryRestConfiguration} bean, which you can define in
+ * your own <code>ApplicationContext</code> (which can take the form of an XML file in the classpath at location
+ * 'META-INF/spring-data-rest/' with a name that ends with '-export.xml').
+ *
+ * @author Jon Brisbin
  */
 @Configuration
 @ImportResource("classpath*:META-INF/spring-data-rest/**/*-export.xml")
 public class RepositoryRestMvcConfiguration {
 
+  /**
+   * {@link org.springframework.data.rest.repository.RepositoryExporter} implementation for exporting JPA repositories.
+   */
   @Autowired(required = false)
   JpaRepositoryExporter customJpaRepositoryExporter;
 
+  /**
+   * {@link org.springframework.context.ApplicationListener} implementation for invoking {@link
+   * org.springframework.validation.Validator} instances assigned to specific domain types.
+   */
   @Autowired(required = false)
   ValidatingRepositoryEventListener validatingRepositoryEventListener;
 
+  /**
+   * Main configuration for the REST exporter.
+   */
   @Autowired(required = false)
   RepositoryRestConfiguration repositoryRestConfig = RepositoryRestConfiguration.DEFAULT;
 
+  /**
+   * For getting access to the {@link javax.persistence.EntityManagerFactory}.
+   *
+   * @return
+   */
   @Bean public PersistenceAnnotationBeanPostProcessor persistenceAnnotationBeanPostProcessor() {
     return new PersistenceAnnotationBeanPostProcessor();
   }
 
+  /**
+   * Use the pre-defined {@link JpaRepositoryExporter} defined by the user or create a default one.
+   *
+   * @return
+   */
   @Bean public JpaRepositoryExporter jpaRepositoryExporter() {
     if(null == customJpaRepositoryExporter) {
       return new JpaRepositoryExporter();
@@ -40,6 +67,11 @@ public class RepositoryRestMvcConfiguration {
     }
   }
 
+  /**
+   * Use the pre-defined {@link ValidatingRepositoryEventListener} defined by the user or create a default one.
+   *
+   * @return
+   */
   @Bean public ValidatingRepositoryEventListener validatingRepositoryEventListener() {
     if(null == validatingRepositoryEventListener) {
       return new ValidatingRepositoryEventListener();
@@ -48,19 +80,43 @@ public class RepositoryRestMvcConfiguration {
     }
   }
 
+  /**
+   * The main REST exporter Spring MVC controller.
+   *
+   * @return
+   *
+   * @throws Exception
+   */
   @Bean public RepositoryRestController repositoryRestController()
       throws Exception {
     return new RepositoryRestController();
   }
 
+  /**
+   * Special {@link org.springframework.web.servlet.HandlerAdapter} that only recognizes handler methods defined in the
+   * {@link RepositoryRestController} class.
+   *
+   * @return
+   */
   @Bean public RepositoryRestHandlerAdapter repositoryExporterHandlerAdapter() {
     return new RepositoryRestHandlerAdapter(repositoryRestConfig);
   }
 
+  /**
+   * Special {@link org.springframework.web.servlet.HandlerMapping} that only recognizes handler methods defined in the
+   * {@link RepositoryRestController} class.
+   *
+   * @return
+   */
   @Bean public RepositoryRestHandlerMapping repositoryExporterHandlerMapping() {
     return new RepositoryRestHandlerMapping();
   }
 
+  /**
+   * Bean for looking up methods annotated with {@link org.springframework.web.bind.annotation.ExceptionHandler}.
+   *
+   * @return
+   */
   @Bean public ExceptionHandlerExceptionResolver exceptionHandlerExceptionResolver() {
     ExceptionHandlerExceptionResolver er = new ExceptionHandlerExceptionResolver();
     er.setCustomArgumentResolvers(