Merge pull request #508 from snicoll/docs

* docs:
  Review first 8 parts of the doc

spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc

@@ -4,7 +4,7 @@
 [partintro]
 --
 Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a
-variety of features, including the packaging of executable jars. The section provides
+variety of features, including the packaging of executable jars. This section provides
 more details on both plugins, as well as some help should you need to extend an
 unsupported build system. If you are just getting started, you might want to read
 ``<<using-spring-boot.adoc#using-boot-build-systems>>'' from the
@@ -155,9 +155,11 @@ The following configuration options are available for the `spring-boot:repackage
 |Name |Description
 
 |`classifier`
-|Classifier to add to the artifact generated. If given, the artifact will be attached. If
+|Classifier to add to the generated artifact. If given, the artifact will be attached. If
  this is not given, it will merely be written to the output directory according to the
- `finalName`.
+ `finalName`. Attaching the artifact allows to deploy it alongside to the original one,
+ see http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-with-classifiers.html[
+ the maven documentation for more details]
 
 |`mainClass`
 |The name of the main class. If not specified will search for a single compiled class
@@ -362,7 +364,7 @@ default) reloadable in the live application, which can be helpful at development
 [[build-tool-plugins-gradle-repackage-configuration]]
 === Repackage configuration
 The gradle plugin automatically extends your build script DSL with a `springBoot` element
-for configuration. Simply set the appropriate properties as you would any other Gradle
+for configuration. Simply set the appropriate properties as you would with any other Gradle
 extension (see below for a list of configuration options):
 
 [source,groovy,indent=0,subs="verbatim,attributes"]
@@ -379,7 +381,7 @@ extension (see below for a list of configuration options):
 Sometimes it may be more appropriate to not package default dependencies resolved from
 `compile`, `runtime` and `provided` scopes. If the created executable jar file
 is intended to be run as it is, you need to have all dependencies nested inside it;
-however, if the plan is to explode a jar file and run main class manually, you may already
+however, if the plan is to explode a jar file and run the main class manually, you may already
 have some of the libraries available via `CLASSPATH`. This is a situation where
 you can repackage your jar with a different set of dependencies.
 

spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc

@@ -102,7 +102,7 @@ information is exposed to the application as environment variables (for example:
 environment variables are language agnostic.
 
 Environment variables don't always make for the easiest API so Spring Boot automatically
-extracts then and flattens the data into properties that can be accessed through
+extracts them and flattens the data into properties that can be accessed through
 Spring's `Environment` abstraction:
 
 [source,java,indent=0]
@@ -232,7 +232,7 @@ that covers the steps that you need to follow when deploying to CloudBees.
 == What to read next
 Check out the http://www.cloudfoundry.com/[Cloud Foundry], https://www.heroku.com/[Heroku]
 and http://www.cloudbees.com[CloudBees] web sites for more information about the kinds of
-features that a PaaS can offer. These are just three of the more popular Java PaaS
+features that a PaaS can offer. These are just three of the most popular Java PaaS
 providers, since Spring Boot is so amenable to cloud-based deployment you free to
 consider other providers as well.
 

spring-boot-docs/src/main/asciidoc/getting-started.adoc

@@ -469,8 +469,8 @@ that provides useful Maven defaults. It also provides a `dependency-management`
 so that you can omit `version` tags for ``blessed'' dependencies.
 
 Other ``Starter POMs'' simply provide dependencies that you are likely to need when
-developing a specific type of application. Since we are developing web application we will
-add a `spring-boot-starter-web` dependency -- but before that, lets look at what we
+developing a specific type of application. Since we are developing a web application, we
+will add a `spring-boot-starter-web` dependency -- but before that, lets look at what we
 currently have.
 
 [indent=0]
@@ -486,7 +486,7 @@ currently have.
 ----
 
 The `mvn dependency:tree` command prints tree representation of your project dependencies.
-You can see that `spring-boot-starter-parent` has already provides some useful test
+You can see that `spring-boot-starter-parent` has already provided some useful test
 dependencies. Lets edit our `pom.xml` and add the `spring-boot-starter-web` dependency
 just below the `parent` section:
 
@@ -508,8 +508,8 @@ additional dependencies, including the Tomcat web server and Spring Boot itself.
 [[getting-started-first-application-code]]
 === Writing the code
 To finish our application we need to create a single Java file. Maven will compile sources
-from `src/main/java` so you need to create that folder structure, then add a file named
-`src/main/java/Example.java`:
+from `src/main/java` by default so you need to create that folder structure, then add a
+file named `src/main/java/Example.java`:
 
 [source,java,indent=0]
 ----

spring-boot-docs/src/main/asciidoc/index.adoc

@@ -23,6 +23,7 @@ Phillip Webb; Dave Syer; Josh Long;
 :dc-spring-boot-autoconfigure: {dc-root}/org/springframework/boot/autoconfigure
 :dc-spring-boot-actuator: {dc-root}/org/springframework/boot/actuate
 :spring-reference: http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle
+:spring-javadoc: http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework
 :spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
 :spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
 :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb

spring-boot-docs/src/main/asciidoc/production-ready-features.adoc

@@ -13,8 +13,8 @@ Auditing, health and metrics gathering can be automatically applied to your appl
 
 [[production-ready-enabling]]
 == Enabling production-ready features.
-The `spring-boot-actuator` project provides all of Spring Boot's production-ready
-features. The simplist way to enable the features is to add a dependency to the
+The `spring-boot-actuator` module provides all of Spring Boot's production-ready
+features. The simplest way to enable the features is to add a dependency to the
 `spring-boot-starter-actuator` ``Starter POM''.
 
 .Definition of Actuator
@@ -170,7 +170,7 @@ implementation that attempts a simple database test.
 
 [[production-ready-application-info]]
 === Custom application info information
-You can customize the data exposed by the `info` endpoint by settings `info.*` Spring
+You can customize the data exposed by the `info` endpoint by setting `info.*` Spring
 properties. All `Environment` properties under the info key will be automatically
 exposed. For example, you could add the following to your `application.properties`:
 
@@ -244,7 +244,7 @@ for Gradle users, although a little more work is required to generate the proper
 [[production-ready-monitoring]]
 == Monitoring and management over HTTP
 If you are developing a Spring MVC application, Spring Boot Actuator will auto-configure
-all non-sensitive endpoints to be exposed over HTTP. The default convention it to use the
+all non-sensitive endpoints to be exposed over HTTP. The default convention is to use the
 `id` of the endpoint as the URL path. For example, `health` is exposed as `/health`.
 
 
@@ -381,7 +381,7 @@ property to `false`:
 === Using Jolokia for JMX over HTTP
 Jolokia is a JMX-HTTP bridge giving an alternative method of accessing JMX beans. To
 use Jolokia, simply include a dependency to `org.jolokia:jolokia-core`. For example,
-using Maven you you add the following:
+using Maven you would add the following:
 
 [source,xml,indent=0]
 ----
@@ -415,7 +415,7 @@ If you are using Jolokia but you don't want Spring Boot to configure it, simply
 
 [source,properties,indent=0]
 ----
-	jolokia.config.enabled=false
+	endpoints.jolokia.enabled=false
 ----
 
 
@@ -511,7 +511,8 @@ Here is a simple ``hello world'' command that could be loaded from
 ----
 	package commands
 
-	import org.springframework.boot.actuate.endpoint.BeansEndpoint
+	import org.crsh.cli.Usage
+	import org.crsh.cli.Command
 
 	class hello {
 
@@ -621,7 +622,7 @@ Here is a simple example that counts the number of times that a method is invoke
 	}
 ----
 
-TIP: You can use any string as a metric name but you following guidelines of your chosen
+TIP: You can use any string as a metric name but you should follow guidelines of your chosen
 store/graphing technology. Some good guidelines for Graphite are available on
 http://matt.aimonetti.net/posts/2013/06/26/practical-guide-to-graphite-monitoring/[Matt Aimonetti's Blog].
 
@@ -678,7 +679,7 @@ use that directly, or you can simply publish `AuditApplicationEvent` via the Spr
 
 [[production-ready-tracing]]
 == Tracing
-Tracing is automatically enable for all HTTP requests. You can view the `trace` endpoint
+Tracing is automatically enabled for all HTTP requests. You can view the `trace` endpoint
 and obtain basic information about the last few requests:
 
 [source,json,indent=0]

spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -25,7 +25,7 @@ the static `SpringApplication.run` method:
 	}
 ----
 
-When you application starts you should see something similar to the following:
+When your application starts you should see something similar to the following:
 
 [indent=0,subs="attributes"]
 ----
@@ -43,7 +43,7 @@ When you application starts you should see something similar to the following:
 2014-03-04 13:09:56.501  INFO 41370 --- [           main] o.s.b.s.app.SampleApplication            : Started SampleApplication in 2.992 seconds (JVM running for 3.658)
 ----
 
-By default `INFO` logging messages will shown, including some relevant startup details
+By default `INFO` logging messages will be shown, including some relevant startup details
 such as the user that launched the application.
 
 
@@ -103,8 +103,9 @@ context, otherwise there is no way for Spring Boot to create the `ServletContext
 
 [[boot-features-application-events-and-listeners]]
 === Application events and listeners
-In addition to the usual Spring Framework events, such as `ContextRefreshedEvent`, a
-`SpringApplication` sends some additional application events. Some events are actually
+In addition to the usual Spring Framework events, such as
+{spring-javadoc}/context/event/ContextRefreshedEvent.{dc-ext}[`ContextRefreshedEvent`],
+a `SpringApplication` sends some additional application events. Some events are actually
 triggered before the `ApplicationContext` is created.
 
 You can register event listeners in a number of ways, the most common being
@@ -139,7 +140,7 @@ you need to override the default.
 It is also possible to take complete control of the `ApplicationContext` type that will
 be used by calling `setApplicationContextClass(...)`.
 
-TIP: It is often desirable call `setWebEnvironment(false)` when using `SpringApplication`
+TIP: It is often desirable to call `setWebEnvironment(false)` when using `SpringApplication`
 within a JUnit test.
 
 
@@ -255,7 +256,8 @@ following locations and add them to the Spring `Environment`:
 
 The list is ordered by precedence (locations higher in the list override lower items).
 
-NOTE: You can also use YAML ('.yml') files as an alternative to '.properties' (see below)
+NOTE: You can also <<boot-features-external-config-yaml, use YAML ('.yml') files>> as
+an alternative to '.properties'.
 
 If you don't like `application.properties` as the configuration file name you can switch
 to another by specifying a `spring.config.name` environment property. You can also refer
@@ -596,7 +598,7 @@ Logback routing is also included to ensure that dependent libraries that use
 Java Util Logging, Commons Logging, Log4J or SLF4J will all work correctly.
 
 TIP: There are a lot of logging frameworks available for Java. Don't worry if the above
-list seems confusing, generally you won't need to change your logging dependencues and
+list seems confusing, generally you won't need to change your logging dependencies and
 the Spring Boot defaults will work just fine.
 
 
@@ -966,9 +968,9 @@ you can see how to set things up.
 [[boot-features-sql]]
 == Working with SQL databases
 The Spring Framework provides extensive support for working with SQL databases. From
-direct JDBC access using `JdbcTemplate` though to complete ``object relational mapping''
+direct JDBC access using `JdbcTemplate` to complete ``object relational mapping''
 technologies such as Hibernate. Spring Data provides an additional level of functionality,
-creating `Repoistory` implementations directly from interfaces and using conventions to
+creating `Repository` implementations directly from interfaces and using conventions to
 generate queries from your method names.
 
 
@@ -983,7 +985,7 @@ credentials to establish a database connection.
 
 [[boot-features-embedded-database-support]]
 ==== Embedded Database Support
-It's often convenient develop applications using an in-memory embedded database.
+It's often convenient to develop applications using an in-memory embedded database.
 Obviously, in-memory databases do not provide persistent storage; you will need to
 populate your database when your application starts and be prepared to throw away
 data when your application ends.
@@ -1161,7 +1163,7 @@ how-to.
 [[boot-features-spring-data-jpa-repositories]]
 ==== Spring Data JPA Repositories
 Spring Data JPA repositories are interfaces that you can define to access data. JPA
-queries are created automatically from your method names. For example, a `CityRepoistory`
+queries are created automatically from your method names. For example, a `CityRepository`
 interface might declare a `findAllByState(String state)` method to find all cities
 in a given state.
 
@@ -1222,7 +1224,7 @@ http://projects.spring.io/spring-data-gemfire/[Gemfire],
 http://projects.spring.io/spring-data-couchbase/[Couchbase] and
 http://projects.spring.io/spring-data-cassandra/[Cassandra].
 Spring Boot provides auto-configuration for MongoDB; you can make use of the other
-project, but you will need to configure them yourself. Refer to the appropriate
+projects, but you will need to configure them yourself. Refer to the appropriate
 reference documentation at http://projects.spring.io/spring-data.
 
 
@@ -1316,7 +1318,7 @@ See the `MongoOperations` Javadoc for complete details.
 [[boot-features-spring-data-mongo-repositories]]
 ==== Spring Data MongoDB repositories
 Spring Data includes repository support for MongoDB. As with the JPA repositories
-discussed earlier, the basic principal is that queries are constructed for you
+discussed earlier, the basic principle is that queries are constructed for you
 automatically based on method names.
 
 In fact, both Spring Data JPA and Spring Data MongoDB share the same common
@@ -1439,7 +1441,7 @@ useful when testing your application.
 ==== ConfigFileApplicationContextInitializer
 `ConfigFileApplicationContextInitializer` is an `ApplicationContextInitializer` that
 can apply to your tests to load Spring Boot `application.properties` files. You can use
-when you don't need the full features provided by `@SpringApplicationConfiguration`.
+this when you don't need the full features provided by `@SpringApplicationConfiguration`.
 
 [source,java,indent=0]
 ----
@@ -1572,15 +1574,15 @@ when searching for beans.
 NOTE: `@Conditional` annotations are processed when `@Configuration` classes are
 parsed. Auto-configure `@Configuration` is always parsed last (after any user defined
 beans), however, if you are using these annotations on regular `@Configuration` classes,
-care must be take not to refer to bean definitions that have not yet been created.
+care must be taken not to refer to bean definitions that have not yet been created.
 
 
 
 [[boot-features-resource-conditions]]
 ==== Resource conditions
-The `@ConditionalOnResource` annotation allows configuration to be skipped when a specific
-resource is not present. Resources can be specified using the usual Spring conventions,
-for example, `file:/home/user/test.dat`.
+The `@ConditionalOnResource` annotation allows configuration to be included only when a
+specific resource is present. Resources can be specified using the usual Spring
+conventions, for example, `file:/home/user/test.dat`.
 
 
 

spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

@@ -131,7 +131,7 @@ want to change the settings defined in the parent.
 [[using-boot-gradle]]
 === Gradle
 Gradle users can directly import ``starter POMs'' in their `dependencies` section. Unlike
-Maven, there is no ``super parent'' to import.
+Maven, there is no ``super parent'' to import to share some configuration.
 
 [source,groovy,indent=0,subs="attributes"]
 ----
@@ -284,7 +284,7 @@ swap specific technical facets.
 |Imports the Jetty HTTP engine (to be used as an alternative to Tomcat)
 
 |`spring-boot-starter-log4j`
-|Support the Log4J looggin framework
+|Support the Log4J logging framework
 
 |`spring-boot-starter-logging`
 |Import Spring Boot's default logging framework (Logback).
@@ -310,7 +310,7 @@ should be avoided. It can cause particular problems for Spring Boot applications
 use `@ComponentScan` or `@EntityScan` annotations, since every class from every jar,
 will be read.
 
-TIP: We recommend that you use the follow Java's recommended package naming conventions
+TIP: We recommend that you follow Java's recommended package naming conventions
 and use a reversed domain name (for example, `com.example.project`).
 
 
@@ -450,13 +450,13 @@ you can use the exclude attribute of `@EnableAutoConfiguration` to disable them.
 
 [[using-boot-spring-beans-and-dependency-injection]]
 == Spring Beans and dependency injection
-You are free to use any the standard Spring Framework techniques to defines your beans
+You are free to use any of the standard Spring Framework techniques to define your beans
 and their injected dependencies. For simplicity, we often find that using `@ComponentScan`
 to find your beans, in combination with `@Autowired` constructor injection works well.
 
 If you structure your code as suggested above (locating your application class in a root
 package), you can add `@ComponentScan` without any arguments. All of your application
-components (`@Component`, `@Service`, `@Repoistory`, `@Controller` etc.) will be
+components (`@Component`, `@Service`, `@Repository`, `@Controller` etc.) will be
 automatically registered as Spring Beans.
 
 Here is an example `@Service` Bean that uses constructor injection to obtain a