Polish documentation

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

@@ -4,7 +4,7 @@
 [partintro]
 --
 If you're just getting started with Spring Boot, or 'Spring' in general, this is the section
-for you! Here we answer the basic '"`what?`"', '"`how?`"' and '"`why?`"' questions. You'll
+for you! Here we answer the basic "`what?`", "`how?`" and "`why?`" questions. You'll
 find a gentle introduction to Spring Boot along with installation instructions.
 We'll then build our first Spring Boot application, discussing some core principles as
 we go.
@@ -524,7 +524,7 @@ endif::[]
 ----
 
 This should give you a working build, you can test it out by running `mvn package` (you
-can ignore the "`jar will be empty - no content was marked for inclusion!'`" warning for
+can ignore the "`jar will be empty - no content was marked for inclusion!`" warning for
 now).
 
 NOTE: At this point you could import the project into an IDE (most modern Java IDE's

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

@@ -964,10 +964,10 @@ the metrics are exported to a Redis cache for aggregation. The `RedisMetricRepos
 two important parameters to configure it for this purpose: `prefix` and `key` (passed into
 its constructor). It is best to use a prefix that is unique to the application instance
 (e.g. using a random value and maybe the logical name of the application to make it
-possible to correlate with other instances of the same application).  The "key" is used to
-keep a global index of all metric names, so it should be unique "globally", whatever that
-means for your system (e.g.  2 instances of the same system could share a Redis cache if
-they have distinct keys).
+possible to correlate with other instances of the same application).  The "`key`" is used
+to keep a global index of all metric names, so it should be unique "`globally`", whatever
+that means for your system (e.g. two instances of the same system could share a Redis cache
+if they have distinct keys).
 
 Example:
 
@@ -991,33 +991,33 @@ spring.metrics.export.redis.key: keys.metrics.mysystem
 The prefix is constructed with the application name and id at the end, so it can easily be used
 to identify a group of processes with the same logical name later.
 
-NOTE: it's important to set both the key and the prefix. The key is used for all
+NOTE: It's important to set both the `key` and the `prefix`. The key is used for all
 repository operations, and can be shared by multiple repositories. If multiple
 repositories share a key (like in the case where you need to aggregate across them), then
-you normally have a read-only "master" repository that has a short, but identifiable,
-prefix (like "metrics.mysystem"), and many write-only repositories with prefixes that
+you normally have a read-only "`master`" repository that has a short, but identifiable,
+prefix (like "`metrics.mysystem`"), and many write-only repositories with prefixes that
 start with the master prefix (like `metrics.mysystem.*` in the example above). It is
-efficient to read all the keys from a "master" repository like that, but inefficient to
+efficient to read all the keys from a "`master`" repository like that, but inefficient to
 read a subset with a longer prefix (e.g. using one of the writing repositories).
 
-NOTE: the example above uses `MetricExportProperties` to inject and extract the key and
-prefix. This is provided to you as a convenience by Spring Boot, and the defaults for that
-will be sensible, but there is nothing to stop you using your own values as long as they
-follow the recommendations.
+TIP: The example above uses `MetricExportProperties` to inject and extract the key and
+prefix. This is provided to you as a convenience by Spring Boot, configured with sensible
+defaults. There is nothing to stop you using your own values as long as they follow the
+recommendations.
 
 
 
 [[production-ready-metric-writers-export-to-open-tdsb]]
 ==== Example: Export to Open TSDB
 If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark it
-`@ExportMetricWriter` the metrics are exported to http://opentsdb.net/[Open TSDB] for
+`@ExportMetricWriter` metrics are exported to http://opentsdb.net/[Open TSDB] for
 aggregation. The `OpenTsdbHttpMetricWriter` has a `url` property that you need to set
-to the Open TSDB "/put" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
+to the Open TSDB "`/put`" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
 `namingStrategy` that you can customize or configure to make the metrics match the data
 structure you need on the server. By default it just passes through the metric name as an
-Open TSDB metric name and adds a tag "domain" with value "org.springframework.metrics" and
-another tag "process" with value equals to the object hash of the naming strategy. Thus,
-after running the application and generating some metrics (e.g. by pinging the home page)
+Open TSDB metric name, and adds the tags "`domain`" (with value
+"`org.springframework.metrics`") and "`process`" (with the value equal to the object hash
+of the naming strategy). Thus, after running the application and generating some metrics
 you can inspect the metrics in the TDB UI (http://localhost:4242 by default).
 
 Example:
@@ -1072,7 +1072,9 @@ MetricWriter metricWriter() {
 If you provide a `@Bean` of type `JmxMetricWriter` marked `@ExportMetricWriter` the metrics are exported as MBeans to
 the local server (the `MBeanExporter` is provided by Spring Boot JMX autoconfiguration as
 long as it is switched on). Metrics can then be inspected, graphed, alerted etc. using any
-tool that understands JMX (e.g. JConsole or JVisualVM). Example:
+tool that understands JMX (e.g. JConsole or JVisualVM).
+
+Example:
 
 [source,java,indent=0]
 ----
@@ -1098,10 +1100,12 @@ period-separated prefix, and the reader will aggregate (by truncating the metric
 and dropping the prefix). Counters are summed and everything else (i.e. gauges) take their
 most recent value.
 
-This is very useful (for instance) if multiple application instances are feeding to a
-central (e.g. redis) repository and you want to display the results. Particularly
-recommended in conjunction with a `MetricReaderPublicMetrics` for hooking up to the
-results to the "/metrics" endpoint. Example:
+This is very useful if multiple application instances are feeding to a central (e.g.
+Redis) repository and you want to display the results. Particularly recommended in
+conjunction with a `MetricReaderPublicMetrics` for hooking up to the results to the
+"`/metrics`" endpoint.
+
+Example:
 
 [source,java,indent=0]
 ----
@@ -1125,17 +1129,17 @@ results to the "/metrics" endpoint. Example:
   }
 ----
 
-NOTE: the example above uses `MetricExportProperties` to inject and
-extract the key and prefix. This is provided to you as a convenience
-by Spring Boot, and the defaults will be sensible. They are set up in 
-`MetricExportAutoConfiguration`.
+NOTE: The example above uses `MetricExportProperties` to inject and extract the key and
+prefix. This is provided to you as a convenience by Spring Boot, and the defaults will be
+sensible. They are set up in `MetricExportAutoConfiguration`.
 
-NOTE: the `MetricReaders` above are not `@Beans` and are not marked as
-`@ExportMetricReader` because they are just collecting and analysing
-data from other repositories, and don't want to export their values.
+NOTE: The `MetricReaders` above are not `@Beans` and are not marked as
+`@ExportMetricReader` because they are just collecting and analyzing data from other
+repositories, and don't want to export their values.
 
 
 
+[[production-ready-code-hale-metrics]]
 [[production-ready-dropwizard-metrics]]
 === Dropwizard Metrics
 A default `MetricRegistry` Spring bean will be created when you declare a dependency to
@@ -1149,7 +1153,7 @@ endpoint
 When Dropwizard metrics are in use, the default `CounterService` and `GaugeService` are
 replaced with a `DropwizardMetricServices`, which is a wrapper around the `MetricRegistry`
 (so you can `@Autowired` one of those services and use it as normal). You can also create
-"special" Dropwizard metrics by prefixing your metric names with the appropriate type
+"`special`" Dropwizard metrics by prefixing your metric names with the appropriate type
 (i.e. `+timer.*+`, `+histogram.*+` for gauges, and `+meter.*+` for counters).
 
 
@@ -1185,7 +1189,7 @@ and obtain basic information about the last few requests:
 
 [source,json,indent=0]
 ----
-  [{
+[{
     "timestamp": 1394343677415,
     "info": {
       "method": "GET",
@@ -1253,9 +1257,9 @@ In `META-INF/spring.factories` file you have to activate the listener(s):
 
 [indent=0]
 ----
-  org.springframework.context.ApplicationListener=\
-  org.springframework.boot.actuate.system.ApplicationPidFileWriter,
-  org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
+	org.springframework.context.ApplicationListener=\
+	org.springframework.boot.actuate.system.ApplicationPidFileWriter,
+	org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
 ----
 
 

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

@@ -1464,208 +1464,192 @@ features add a `@Bean` of type `WebSecurityConfigurerAdapter` with
 
 
 
+[[boot-features-security-oauth2]]
 === OAuth2
 If you have `spring-security-oauth2` on your classpath you can take advantage of some
-autoconfiguration to make it easy to set up Authorization or Resource Server features by
-configuring some property values in the `Environment`.
+auto-configuration to make it easy to set up Authorization or Resource Server.
 
 
 
+[[boot-features-security-oauth2-authorization-server]]
 ==== Authorization Server
-To create an Authorization Server and grant access tokens you need to
-`@EnableAuthorizationServer` and provide
-`spring.oauth2.client.[clientId,clientSecret]`. The client will be
-registered for you in an in-memory repository. Having done that you
-will be able to use the client credentials to create an access token,
-e.g.
+To create an Authorization Server and grant access tokens you need to use
+`@EnableAuthorizationServer` and provide `spring.oauth2.client.client-id` and
+`spring.oauth2.client.client-secret]` properties. The client will be registered for you
+in an in-memory repository.
 
+Having done that you will be able to use the client credentials to create an access token,
+for example:
+
+[indent=0]
 ----
-$ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd
+	$ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd
 ----
 
-The basic auth credentials for the `/token` endpoint are the client id
-and secret, and the user credentials are the normal Spring Security
-user details (which default in Spring Boot to "user" and a random
-password).
+The basic auth credentials for the `/token` endpoint are the `client-id` and
+`client-secret`. The user credentials are the normal Spring Security user details (which
+default in Spring Boot to "`user`" and a random password).
 
-To switch off the autoconfiguration and configure the Authorization
-Server features yourself just add a `@Bean` of type
-`AuthorizationServerConfigurer`.
+To switch off the auto-configuration and configure the Authorization Server features
+yourself just add a `@Bean` of type `AuthorizationServerConfigurer`.
 
 
 
+[[boot-features-security-oauth2-resource-server]]
 ==== Resource Server
-To use the access token you need a Resource Server (which can be the
-same as the Authorization Server). Creating a Resource Server is easy:
-just add `@EnableResourceServer` and provide some configuration to
-allow the server to decode access tokens. If your app is also an
-Authorization Server it already knows how to decode tokens, so there
-is nothing else to do. If your app is a standalone service then you
-need to give it some more configuration. Here are the options, one of
-the following:
+To use the access token you need a Resource Server (which can be the same as the
+Authorization Server). Creating a Resource Server is easy, just add
+`@EnableResourceServer` and provide some configuration to allow the server to decode
+access tokens. If your appplication is also an Authorization Server it already knows how
+to decode tokens, so there is nothing else to do. If your app is a standalone service then you
+need to give it some more configuration, one of the following options:
 
-* `spring.oauth2.resource.userInfoUri` to use the "/me" resource
-(e.g. "https://uaa.run.pivotal.io/userinfo" on PWS), or
+* `spring.oauth2.resource.user-info-uri` to use the "/me" resource (e.g.
+"`https://uaa.run.pivotal.io/userinfo`" on PWS)
 
-* `spring.oauth2.resource.tokenInfoUri` to use the token decoding endpoint
-(e.g. "https://uaa.run.pivotal.io/check_token" on PWS).
+* `spring.oauth2.resource.token-info-uri` to use the token decoding endpoint (e.g.
+"`https://uaa.run.pivotal.io/check_token`" on PWS).
 
-If you specify both the `userInfoUri` and the `tokenInfoUri` then
-you can set a flag to say that one is preferred over the other
-(`preferTokenInfo=true` is the default).
+If you specify both the `user-info-uri` and the `token-info-uri` then you can set a flag
+to say that one is preferred over the other (`prefer-token-info=true` is the default).
 
-Alternatively (instead of `userInfoUri` or `tokenInfoUri`) if the
-tokens are JWTs you can configure a
-`spring.oauth2.resource.jwt.keyValue` to decode them locally,
-where the key is a verification key. The verification key value is
-either a symmetric secret or PEM-encoded RSA public key. If you don't
-have the key and it's public you can provide a URI where it can be
-downloaded (as a JSON object with a "value" field) with
-`spring.oauth2.resource.jwt.keyUri`. E.g. on PWS:
+Alternatively (instead of `user-info-uri` or `token-info-uri`) if the tokens are JWTs you
+can configure a `spring.oauth2.resource.jwt.key-value` to decode them locally (where the
+key is a verification key). The verification key value is either a symmetric secret or
+PEM-encoded RSA public key. If you don't have the key and it's public you can provide a
+URI where it can be downloaded (as a JSON object with a "`value`" field) with
+`spring.oauth2.resource.jwt.key-uri`. E.g. on PWS:
 
+[indent=0]
 ----
-$ curl https://uaa.run.pivotal.io/token_key
-{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
+	$ curl https://uaa.run.pivotal.io/token_key
+	{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
 ----
 
-WARNING: If you use the `spring.oauth2.resource.jwt.keyUri` the
-authorization server needs to be running when your application starts
-up. It will log a warning if it can't find the key, and tell you what
-to do to fix it.
+WARNING: If you use the `spring.oauth2.resource.jwt.key-uri` the authorization server
+needs to be running when your application starts up. It will log a warning if it can't
+find the key, and tell you what to do to fix it.
 
 
 
+[[boot-features-security-oauth2-token-type]]
 === Token Type in User Info
-Google (and certain other 3rd party identity providers) is more strict
-about the token type name that is sent in the headers to the user info
-endpoint. The default is "Bearer" which suits most providers and
-matches the spec, but if you need to change it you can set
-`spring.oauth2.resource.tokenType`.
+Google, and certain other 3rd party identity providers, are more strict about the token
+type name that is sent in the headers to the user info endpoint. The default is "`Bearer`"
+which suits most providers and matches the spec, but if you need to change it you can set
+`spring.oauth2.resource.token-type`.
 
 
 
+[[boot-features-security-custom-user-info]]
 === Customizing the User Info RestTemplate
-If you have a `userInfoUri`, the Resource Server features use an
-`OAuth2RestTemplate` internally to fetch user details for
-authentication. This is provided as a qualified `@Bean` with id
-"userInfoRestTemplate", but you shouldn't need to know that to just
-use it. The default should be fine for most providers, but
-occasionally you might need to add additional interceptors, or change
-the request authenticator (which is how the token gets attached to
-outgoing requests). To add a customization just create a bean of type
-`UserInfoRestTemplateCustomizer` - it has a single method that will be
-called after the bean is created but before it is initialized. The
-rest template that is being customized here is _only_ used internally
-to carry out authentication.
+If you have a `user-info-uri`, the resource server features use an `OAuth2RestTemplate`
+internally to fetch user details for authentication. This is provided as a qualified
+`@Bean` with id `userInfoRestTemplate`, but you shouldn't need to know that to just
+use it. The default should be fine for most providers, but occasionally you might need to
+add additional interceptors, or change the request authenticator (which is how the token
+gets attached to outgoing requests). To add a customization just create a bean of type
+`UserInfoRestTemplateCustomizer` - it has a single method that will be called after the
+bean is created but before it is initialized. The rest template that is being customized
+here is _only_ used internally to carry out authentication.
 
 [TIP]
 ====
-To set an RSA key value in YAML use the "pipe" continuation
-marker to split it over multiple lines ("|") and remember to indent
-the key value (it's a standard YAML language feature). Example:
+To set an RSA key value in YAML use the "`pipe`" continuation marker to split it over
+multiple lines ("`|`") and remember to indent the key value (it's a standard YAML
+language feature). Example:
 
 [source,yaml,indent=0]
 ----
-        oauth2:
-          resource:
-            jwt:
-              keyValue: |
-                -----BEGIN PUBLIC KEY-----
-                MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
-                -----END PUBLIC KEY-----
+	oauth2:
+		resource:
+			jwt:
+				keyValue: |
+					-----BEGIN PUBLIC KEY-----
+					MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
+					-----END PUBLIC KEY-----
 ----
 ====
 
 
 
+[[boot-features-security-custom-user-info-client]]
 ==== Client
-To make your webapp into an OAuth2 client you can simply
-`@EnableOAuth2Client` and Spring Boot will create an
-`OAuth2RestTemplate` for you to autowire. It uses the
-`spring.oauth2.client.*` as credentials (the same as you might be
-using in the Authorization Server), but in addition it will need to
-know the authorization and token URIs in the Authorization Server. For
-example:
+To make your webapp into an OAuth2 client you can simply add `@EnableOAuth2Client` and
+Spring Boot will create an `OAuth2RestTemplate` for you to `@Autowire`. It uses the
+`spring.oauth2.client.*` as credentials (the same as you might be using in the
+Authorization Server), but in addition it will need to know the authorization and token
+URIs in the Authorization Server. For example:
 
 .application.yml
-[source,yaml]
+[source,yaml,indent=0]
 ----
 spring:
-  oauth2:
-    client:
-      clientId: bd1c0a783ccdd1c9b9e4
-      clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
-      accessTokenUri: https://github.com/login/oauth/access_token
-      userAuthorizationUri: https://github.com/login/oauth/authorize
-      clientAuthenticationScheme: form
-----
-
-An app with this configuration will redirect to github for
-authorization if you attempt to use the `OAuth2RestTemplate`. If you
-are already signed into github you won't even notice that it has
-authenticated.  These specific credentials will only work if your app
-is running on port 8080 (register your own client app in Github or
-other provider for more flexibility).
-
-To limit the scope that the client asks for when it obtains an access token
-you can set `spring.oauth2.client.scope` (comma separated or an array in YAML). By
-default the scope is empty and it is up to to Authorization Server to
-decide what the defaults should be, usually depending on the settings in
-the client registration that it holds.
-
-NOTE: There is also a setting for
-`spring.oauth2.client.clientAuthenticationScheme` which defaults to
-"header" (but you might need to set it to "form" if, like Github for
-instance, your OAuth2 provider doesn't like header authentication). In
-fact, the `spring.oauth2.client.*` properties are bound to an instance
-of `AuthorizationCodeResourceDetails` so all its properties can be
-specified.
-
-TIP: In a non-web application you can still `@Autowired` an
-`OAuth2RestOperations` and it is still wired into the
-`spring.oauth2.client.*` configuration, but in this case it is a
-client credentials token grant you will be asking for if you use it
-(and there is no need to use `@EnableOAuth2Client` or
-`@EnableOAuth2Sso`). To switch it off, just remove the
-`spring.oauth2.client.clientId` from your configuration (or make it
-the empty string).
-
-
-
+	oauth2:
+		client:
+			clientId: bd1c0a783ccdd1c9b9e4
+			clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
+			accessTokenUri: https://github.com/login/oauth/access_token
+			userAuthorizationUri: https://github.com/login/oauth/authorize
+			clientAuthenticationScheme: form
+----
+
+An application with this configuration will redirect to Github for authorization when you
+attempt to use the `OAuth2RestTemplate`. If you are already signed into Github you won't
+even notice that it has authenticated.  These specific credentials will only work if your
+application is running on port 8080 (register your own client app in Github or other
+provider for more flexibility).
+
+To limit the scope that the client asks for when it obtains an access token you can set
+`spring.oauth2.client.scope` (comma separated or an array in YAML). By default the scope
+is empty and it is up to to Authorization Server to decide what the defaults should be,
+usually depending on the settings in the client registration that it holds.
+
+NOTE: There is also a setting for `spring.oauth2.client.client-authentication-scheme`
+which defaults to "`header`" (but you might need to set it to "`form`" if, like Github for
+instance, your OAuth2 provider doesn't like header authentication). In fact, the
+`spring.oauth2.client.*` properties are bound to an instance of
+`AuthorizationCodeResourceDetails` so all its properties can be specified.
+
+TIP: In a non-web application you can still `@Autowire` an `OAuth2RestOperations` and it
+is still wired into the `spring.oauth2.client.*` configuration. In this case it is a
+"`client credentials token grant`" you will be asking for if you use it (and there is no
+need to use `@EnableOAuth2Client` or `@EnableOAuth2Sso`). To switch it off, just remove
+the `spring.oauth2.client.client-id` from your configuration (or make it the empty
+string).
+
+
+
+[[boot-features-security-oauth2-single-sign-on]]
 ==== Single Sign On
-An OAuth2 Client can be used to fetch user details from the provider
-if such features are provided (e.g. by using the `userInfoUri` that
-the Resource Server supports as above), and then the user details can
-be converted to an `Authentication` token for Spring Security. This is
-the basis for a Single Sign On (SSO) protocol based on OAuth2, and
-Spring Boot makes it easy to participate by providing an annotation
-`@EnableOAuth2Sso`. The Github client above can protect all its
-resources and authenticate using the Github `/user/` endpoint, by
-adding that annotation and declaring where to find the endpoint (in
-addition to the `spring.oauth2.client.*` configuration already listed
-above):
+An OAuth2 Client can be used to fetch user details from the provider (if such features are
+available) and then convert them into an `Authentication` token for Spring Security.
+The Resource Server above support this via the `user-info-uri` property This is the basis
+for a Single Sign On (SSO) protocol based on OAuth2, and Spring Boot makes it easy to
+participate by providing an annotation `@EnableOAuth2Sso`. The Github client above can
+protect all its resources and authenticate using the Github `/user/` endpoint, by adding
+that annotation and declaring where to find the endpoint (in addition to the
+`spring.oauth2.client.*` configuration already listed above):
 
 .application.yml
-[source,yaml]
+[source,yaml,indent=0]]
 ----
-spring:
-  oauth2:
-...
-    resource:
-      userInfoUri: https://api.github.com/user
-      preferTokenInfo: false
-----
-
-Since all paths are secure by default, there is no "home" page that
-you can show to unauthenticated users and invite them to login (by
-visiting the `/login` path, or the path specified by
-`spring.oauth2.sso.loginPath`).
-
-To customize the access rules or paths to protect, so you can add a
-"home" page for instance, `@EnableOAuth2Sso` can be added to a
-`WebSecurityConfigurerAdapter` and the annotation will cause it to be
-decorated and enhanced with the necessary pieces to get the `/login`
-path working. For example, here we simply allow unauthenticated access
+	spring:
+		oauth2:
+	...
+		resource:
+			userInfoUri: https://api.github.com/user
+			preferTokenInfo: false
+----
+
+Since all paths are secure by default, there is no "`home`" page that you can show to
+unauthenticated users and invite them to login (by visiting the `/login` path, or the
+path specified by `spring.oauth2.sso.login-path`).
+
+To customize the access rules or paths to protect, so you can add a "`home`" page for
+instance, `@EnableOAuth2Sso` can be added to a `WebSecurityConfigurerAdapter` and the
+annotation will cause it to be decorated and enhanced with the necessary pieces to get
+the `/login` path working. For example, here we simply allow unauthenticated access
 to the home page at "/" and keep the default for everything else:
 
 [source,java,indent=0]
@@ -1688,6 +1672,7 @@ to the home page at "/" and keep the default for everything else:
 
 
 
+[[boot-features-security-actuator]]
 === Actuator Security
 If the Actuator is also in use, you will find:
 
@@ -2301,12 +2286,13 @@ TIP: For complete details of Spring Data Elasticsearch, refer to their
 http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation].
 
 
+
 [[boot-features-caching]]
 == Caching
-The Spring Framework provides support for transparently adding caching into an
-application. At its core, the abstraction applies caching to methods, reducing thus the
-number of executions based on the information available in the cache. The caching logic
-is applied transparently without any interference to the invoker.
+The Spring Framework provides support for transparently adding caching to an application.
+At its core, the abstraction applies caching to methods, reducing thus the number of
+executions based on the information available in the cache. The caching logic is applied
+transparently, without any interference to the invoker.
 
 NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
 reference for more details.
@@ -2324,7 +2310,9 @@ relevant annotation to its method:
 	public class MathService {
 
 		@CacheResult
-		public int computePiDecimal(int i) { ... }
+		public int computePiDecimal(int i) {
+			// ...
+		}
 
 	}
 ----
@@ -2339,16 +2327,17 @@ TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
 
 
 === Supported cache providers
-NOTE: To easily get started, just add `spring-boot-starter-cache` to the dependencies of
-your application.
-
 The cache abstraction does not provide an actual store and relies on a abstraction
 materialized by the `org.springframework.cache.Cache` and
 `org.springframework.cache.CacheManager` interfaces. Spring Boot auto-configures a
 suitable `CacheManager` according to the implementation as long as the caching support is
 enabled via the `@EnableCaching` annotation.
 
-Spring Boot tries to detect the following providers (in that order):
+TIP: Use the `spring-boot-starter-cache` "`Starter POM`" to quickly add required caching
+dependencies. If you are adding dependencies manually you should note that certain
+implementations are only provided by the `spring-context-support` jar.
+
+Spring Boot tries to detect the following providers (in this order):
 
 * <<boot-features-caching-provider-generic,Generic>>
 * <<boot-features-caching-provider-ehcache2,EhCache 2.x>>
@@ -2366,38 +2355,40 @@ property.
 
 [[boot-features-caching-provider-generic]]
 ==== Generic
-If the context defines _at least_ one `org.springframework.cache.Cache` bean, a
-`CacheManager` wrapping them is configured.
+Generic caching is used if the context defines _at least_ one
+`org.springframework.cache.Cache` bean, a `CacheManager` wrapping them is configured.
 
 
 
 [[boot-features-caching-provider-ehcache2]]
 ==== EhCache 2.x
-EhCache 2.x tries to locate a configuration file named `ehcache.xml` at the root of the
+EhCache 2.x is used if a file named `ehcache.xml` can be found at the root of the
 classpath. If EhCache 2.x and such file is present it is used to bootstrap the cache
-manager. An alternate configuration file can be provide a well:
+manager. An alternate configuration file can be provide a well using:
 
 [source,properties,indent=0]
 ----
 	spring.cache.ehcache.config=classpath:config/another-config.xml
 ----
 
+
+
 [[boot-features-caching-provider-hazelcast]]
 ==== Hazelcast
-
-Hazelcast tries to locate its configuration file as follows: An `hazelcast.xml` file
-stored either in the current working directory or at the root of the classpath, or a
-location specified via the `hazelcast.config` system property. Spring Boot detects all
-of these and allow for explicit location as well:
+Hazelcast is used if a `hazelcast.xml` file can be found in the current working
+directory, at the root of the classpath or a location specified via the `hazelcast.config`
+system property. Spring Boot detects all of these and also allows for explicit location
+using:
 
 [source,properties,indent=0]
 ----
 	spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml
 ----
 
+
+
 [[boot-features-caching-provider-infinispan]]
 ==== Infinispan
-
 Infinispan has no default configuration file location so it must be specified explicitly
 (or the default bootstrap is used).
 
@@ -2423,7 +2414,6 @@ configuration file, Spring Boot does its best to accommodate with implementation
 ----
     # Only necessary if more than one provider is present
 	spring.cache.jcache.provider=com.acme.MyCachingProvider
-
 	spring.cache.jcache.config=classpath:acme.xml
 ----
 
@@ -2456,7 +2446,7 @@ property.
 ==== Guava
 If Guava is present, a `GuavaCacheManager` is auto-configured. Caches can be created
 on startup using the `spring.cache.cache-names` property and customized by one of the
-following (in that order):
+following (in this order):
 
 1. A cache spec defined by `spring.cache.guava.spec`
 2. A `com.google.common.cache.CacheBuilderSpec` bean is defined

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

@@ -238,7 +238,7 @@ where `+*+` is a particular type of application. This naming structure is intend
 help when you need to find a starter. The Maven integration in many IDEs allow you to
 search dependencies by name. For example, with the appropriate Eclipse or STS plugin
 installed, you can simply hit `ctrl-space` in the POM editor and type
-''spring-boot-starter'' for a complete list.
+"`spring-boot-starter`" for a complete list.
 
 Third party starters should not start with `spring-boot-starter` as it is reserved for
 official starters. A third-party starter for `acme` will be typically named