DATAREST-1246 - Full edit of the reference docs.

I edited for grammar, punctuation, spelling, usage, and corporate voice. I also added the epub-cover image (and the SVG file from which it can be generated).

Author: Jay Bryant

src/main/asciidoc/adding-sdr-to-spring-mvc-app.adoc

@@ -1,14 +1,13 @@
 [[customizing-sdr.adding-sdr-to-spring-mvc-app]]
-= Adding Spring Data REST to an existing Spring MVC Application
+= Adding Spring Data REST to an Existing Spring MVC Application
 
-NOTE: The following steps are unnecessary if you are using Spring Boot. Adding *spring-boot-starter-data-rest* will cause it to automatically to get added to your application.
+NOTE: The following steps are unnecessary if you use Spring Boot. For Boot applications, adding `spring-boot-starter-data-rest` automatically adds Spring Data REST to your application.
 
-If you have an existing Spring MVC application and you'd like to integrate Spring Data REST, it's actually very easy.
-
-Somewhere in your Spring MVC configuration (most likely where you configure your MVC resources) add a bean reference to the JavaConfig class that is responsible for configuring the `RepositoryRestController`. The class name is `org.springframework.data.rest.webmvc.RepositoryRestMvcConfiguration`.
+You can integrate Spring Data REST with an existing Spring MVC application. In your Spring MVC configuration (most likely where you configure your MVC resources), add a bean reference to the Java configuration class that is responsible for configuring the `RepositoryRestController`. The class name is `org.springframework.data.rest.webmvc.RepositoryRestMvcConfiguration`. The following example shows how to use an `@Import` annotation to add the proper reference:
 
 In Java, this would look like:
 
+====
 [source,java]
 ----
 import org.springframework.context.annotation.Import;
@@ -21,24 +20,27 @@ public class MyApplicationConfiguration {
   …
 }
 ----
+====
 
-In XML this would look like:
+The following example shows the corresponding XML configuration:
 
+====
 [source,xml]
 ----
 <bean class="org.springframework.data.rest.webmvc.config.RepositoryRestMvcConfiguration"/>
 ----
+====
 
-When your ApplicationContext comes across this bean definition it will bootstrap the necessary Spring MVC resources to fully-configure the controller for exporting the repositories it finds in that `ApplicationContext` and any parent contexts.
+When your ApplicationContext comes across this bean definition, it bootstraps the necessary Spring MVC resources to fully configure the controller for exporting the repositories it finds in that `ApplicationContext` and any parent contexts.
 
-== More on required configuration
+== More on Required Configuration
 
-There are a couple Spring MVC resources that Spring Data REST depends on that must be configured correctly for it to work inside an existing Spring MVC application. We've tried to isolate those resources from whatever similar resources already exist within your application, but it may be that you want to customize some of the behavior of Spring Data REST by modifying these MVC components.
+Spring Data REST depends on a couple Spring MVC resources that must be configured correctly for it to work inside an existing Spring MVC application. We tried to isolate those resources from whatever similar resources already exist within your application, but it may be that you want to customize some of the behavior of Spring Data REST by modifying these MVC components.
 
-The most important things that we configure especially for use by Spring Data REST include:
+You should pay special attention to configuring `RepositoryRestHandlerMapping`, covered in the next section.
 
-=== RepositoryRestHandlerMapping
+=== `RepositoryRestHandlerMapping`
 
-We register a custom `HandlerMapping` instance that responds only to the `RepositoryRestController` and only if a path is meant to be handled by Spring Data REST. In order to keep paths that are meant to be handled by your application separate from those handled by Spring Data REST, this custom `HandlerMapping` inspects the URL path and checks to see if a Repository has been exported under that name. If it has, it allows the request to be handled by Spring Data REST. If there is no Repository exported under that name, it returns `null`, which just means "let other `HandlerMapping` instances try to service this request".
+We register a custom `HandlerMapping` instance that responds only to the `RepositoryRestController` and only if a path is meant to be handled by Spring Data REST. In order to keep paths that are meant to be handled by your application separate from those handled by Spring Data REST, this custom `HandlerMapping` class inspects the URL path and checks to see if a repository has been exported under that name. If it has, the custom `HandlerMapping` class lets the request be handled by Spring Data REST. If there is no Repository exported under that name, it returns `null`, which means "`let other `HandlerMapping` instances try to service this request`".
 
-The Spring Data REST `HandlerMapping` is configured with `order=(Ordered.LOWEST_PRECEDENCE - 100)` which means it will usually be first in line when it comes time to map a URL path. Your existing application will never get a chance to service a request that is meant for a repository. For example, if you have a repository exported under the name "person", then all requests to your application that start with `/person` will be handled by Spring Data REST and your application will never see that request. If your repository is exported under a different name, however (like "people"), then requests to `/people` will go to Spring Data REST and requests to "/person" will be handled by your application.
+The Spring Data REST `HandlerMapping` is configured with `order=(Ordered.LOWEST_PRECEDENCE - 100)`, which means it is usually first in line when it comes time to map a URL path. Your existing application never gets a chance to service a request that is meant for a repository. For example, if you have a repository exported under the name of `person`, then all requests to your application that start with `/person` are handled by Spring Data REST, and your application never sees that request. If your repository is exported under a different name (such as `people`), however, then requests to `/people` go to Spring Data REST and requests to `/person` are handled by your application.

src/main/asciidoc/configuring-cors.adoc

@@ -1,37 +1,42 @@
 [[customizing-sdr.configuring-cors]]
 = Configuring CORS
 
-For security reasons, browsers prohibit AJAX calls to resources residing outside the current origin. When working with client-side HTTP requests issued by a browser you want to enable specific HTTP resources to be accessible.
+For security reasons, browsers prohibit AJAX calls to resources residing outside the current origin. When working with client-side HTTP requests issued by a browser, you want to enable specific HTTP resources to be accessible.
 
-Spring Data REST supports as of 2.6 http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) through http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/web.html#mvc-cors[Spring's CORS] support.
+Spring Data REST, as of 2.6, supports http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-Origin Resource Sharing] (CORS) through http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/web.html#mvc-cors[Spring's CORS] support.
 
 
-== Repository interface CORS configuration
+== Repository Interface CORS Configuration
 
-You can add a `@CrossOrigin` annotation to your repository interfaces to enable CORS for the whole repository. By default `@CrossOrigin` allows all origins and HTTP methods:
+You can add a `@CrossOrigin` annotation to your repository interfaces to enable CORS for the whole repository. By default, `@CrossOrigin` allows all origins and HTTP methods. The following example shows a cross-origin repository interface definition:
 
+====
 [source, java]
 ----
 @CrossOrigin
 interface PersonRepository extends CrudRepository<Person, Long> {}
 ----
+====
 
-In the above example CORS support is enabled for the whole `PersonRepository`. `@CrossOrigin` provides attributes to configure CORS support.
+In the preceding example, CORS support is enabled for the whole `PersonRepository`. `@CrossOrigin` provides attributes to configure CORS support, as the following example shows:
 
+====
 [source, java]
 ----
 @CrossOrigin(origins = "http://domain2.com",
   methods = { RequestMethod.GET, RequestMethod.POST, RequestMethod.DELETE },
   maxAge = 3600)
 interface PersonRepository extends CrudRepository<Person, Long> {}
 ----
+====
 
-This example enables CORS support for the whole `PersonRepository` providing one origin, restricted to `GET`, `POST` and `DELETE` methods with a max age of 3600 seconds.
+The preceding example enables CORS support for the whole `PersonRepository` by providing one origin, restricted to the `GET`, `POST`, and `DELETE` methods and with a max age of 3600 seconds.
 
-== Repository REST Controller method CORS configuration
+== Repository REST Controller Method CORS Configuration
 
-Spring Data REST fully supports http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/web.html#controller-method-cors-configuration[Spring Web MVC's Controller method configuration] on custom REST Controllers sharing repository base paths.
+Spring Data REST fully supports http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/web.html#controller-method-cors-configuration[Spring Web MVC's controller method configuration] on custom REST controllers that share repository base paths, as the following example shows:
 
+====
 [source, java]
 ----
 @RepositoryRestController
@@ -44,15 +49,19 @@ public class PersonController {
   }
 }
 ----
+====
 
 NOTE: Controllers annotated with `@RepositoryRestController` inherit `@CrossOrigin` configuration from their associated repositories.
 
-== Global CORS configuration
+== Global CORS Configuration
 
-In addition to fine-grained, annotation-based configuration you’ll probably want to define some global CORS configuration as well. This is similar to Spring Web MVC'S CORS configuration but can be declared within Spring Data REST and combined with fine-grained `@CrossOrigin` configuration. By default all origins and `GET`, `HEAD`, and `POST` methods are allowed.
+In addition to fine-grained, annotation-based configuration, you probably want to define some global CORS configuration as well. This is similar to Spring Web MVC'S CORS configuration but can be declared within Spring Data REST and combined with fine-grained `@CrossOrigin` configuration. By default, all origins and `GET`, `HEAD`, and `POST` methods are allowed.
 
 NOTE: Existing Spring Web MVC CORS configuration is not applied to Spring Data REST.
 
+The following example sets an allowed origin, adds the PUT and DELETE HTTP methods, adds and exposes some headers, and sets a maximum age of an hour:
+
+====
 [source, java]
 ----
 @Component
@@ -70,4 +79,4 @@ public class SpringDataRestCustomization extends RepositoryRestConfigurerAdapter
   }
 }
 ----
-
+====