Merge pull request #714 from hansjorg/doc-changes

Small language changes

Author: jknack

md/app.md

@@ -70,7 +70,7 @@ public class MyModule implements Jooby.Module {
 }
 ```
 
-The `onStart` callbacks are part of bootstrap and executed before server is ready. The `onStarted` callbacks are executed when server is ready.
+The `onStart` callbacks are part of bootstrap and executed before the server is ready. The `onStarted` callbacks are executed when the server is ready.
 
 Modules are covered later all you need to know now is that you can start/stop module as you usually do from your application. 
 
@@ -95,7 +95,7 @@ Callback order is preserved:
 }
 ```
 
-Order is useful for service dependencies, like `ServiceB` should be started after `ServiceA`.
+Order is useful for service dependencies, for example if `ServiceB` should be started after `ServiceA`.
 
 ### service registry
 
@@ -117,7 +117,7 @@ You have access to the the service registry from start/stop events:
 
 ### PostConstruct/PreDestroy annotations
 
-If you prefer the annotation way then:
+If you prefer annotations you can do:
 
 ```java
 @Singleton

md/asset-processor.md

@@ -1,10 +1,10 @@
 # asset processor
 
-Checks, validate and/or modify asset contents. An [AssetProcessor]({{defdocs}}/assets/AssetProcessor.html) is usually provided as a separated dependency.
+Checks, validates and/or modifies asset contents. An [AssetProcessor]({{defdocs}}/assets/AssetProcessor.html) is usually provided as a separate dependency.
 
-## how to use it?
+## usage
 
-First thing to do is to add the dependency:
+Start by adding the dependency to your ```pom.xml```:
 
 ```xml
   <dependency>
@@ -14,9 +14,10 @@ First thing to do is to add the dependency:
   </dependency>
 ```
 
-Did you see the **provided** scope? We just need the processor for development, because assets are processed at runtime. In ```prod```, assets are processed at built-time via Maven/Gradle plugin, so we don't need this library/dependency. This also, helps to keep our dependencies and the jar size small.
+Notice the **provided** scope. The processor is only required for development, since the assets are processed at runtime in this case. In ```prod```, assets are processed at build-time via the Maven or Gradle plugins, so the dependency is not needed there. This also helps to keep the number of dependencies and the jar size smaller.
+
+After the dependency is declared, all that's needed is to add the processor to the pipeline:
 
-Now we have the dependency all we have to do is to add it to our pipeline:
 
 ```text
 assets {
@@ -28,7 +29,7 @@ assets {
 
 ## configuration
 
-It is possible to configure or set options too:
+It's possible to configure or set options as well:
 
 ```text
 assets {
@@ -42,7 +43,7 @@ assets {
 }
 ```
 
-Previous example, set a ```foo``` property to ```bar```! Options can be set per environment too:
+The previous example sets the ```foo``` property to ```bar```. Options can be set per environment as well:
 
 ```text
 assets {
@@ -62,11 +63,11 @@ assets {
 }
 ```
 
-Here, in ```dev``` processor has two properties: ```foo:foo``` and ```bar:bar```, while in ```dist``` the processor only has ```foo:bar```
+In this example, the processor will have two properties in the ```dev``` environment: ```foo:foo``` and ```bar:bar```, while in ```dist``` the processor will only have ```foo:bar```
 
 ## binding
 
-The ```my-processor``` will be resolved it to: ```org.jooby.assets.MyProcessor``` class. The processor name is converted to ```MyProcessor```, it converts the hyphenated name to upper camel and by default processors are defined in the ```org.jooby.assets``` package.
+The ```my-processor``` token will be resolved to the: ```org.jooby.assets.MyProcessor``` class. The processor name is converted to ```MyProcessor``` by converting the hyphenated name to upper camel case and by placing it in the ```org.jooby.assets``` package (a default for processors).
 
 A custom binding is provided via the ```class``` property:
 
@@ -86,9 +87,9 @@ assets {
 
 Contributes new or dynamically generated content to a ```fileset```. Content generated by an aggregator might be processed by an {@link AssetProcessor}.
 
-## how to use it?
+## usage
 
-First thing to do is to add the dependency:
+Start by adding the dependency to your ```pom.xml```:
 
 ```xml
 <dependency>
@@ -99,9 +100,9 @@ First thing to do is to add the dependency:
 
 ```
 
-Did you see the **provided** scope? We just need the aggregator for development, because assets are processed at runtime. In ```prod```, assets are processed at built-time via Maven/Gradle plugin, so we don't need it. This also, helps to keep our dependencies and the jar size small.
+Notice the **provided** scope. The aggregator is only required for development, since the assets are processed at runtime in this case. In ```prod```, assets are processed at build-time via the Maven or Gradle plugins, so the dependency is not needed there. This also helps to keep the number of dependencies and the jar size smaller.
 
-Now we have the dependency all we have to do is to add the ```svg-sprites``` aggregator to a fileset:
+After the dependency is declared, all that's needed is to add the ```svg-sprites``` aggregator to a fileset:
 
 ```
 assets {
@@ -124,7 +125,7 @@ assets {
 }
 ```
 
-Here for example, the ```svg-sprites``` aggregator contributes the ```css/sprite.css``` file to the ```home``` fileset. The fileset then looks like:
+In this example, the ```svg-sprites``` aggregator contributes the ```css/sprite.css``` file to the ```home``` fileset. The fileset then looks like:
 
 ```
 assets {
@@ -138,7 +139,7 @@ assets {
 }
 ```
 
-It replaces the aggregator name with one or more files from [AssetAggregator.fileset]({{defdocs}}/assets/AssetAggregator.html#fileset--) method.
+It replaces the aggregator name with one or more files from the [AssetAggregator.fileset]({{defdocs}}/assets/AssetAggregator.html#fileset--) method.
 
 # available processors
 

md/assets-require.md

@@ -1 +1 @@
-Make sure you already setup the [assets module](https://github.com/jooby-project/jooby/tree/master/jooby-assets) in your project!
+Make sure you've already set up the [assets module](https://github.com/jooby-project/jooby/tree/master/jooby-assets) in your project!

md/async.md

@@ -1,14 +1,14 @@
 # thread model
 
-You can see {{jooby}} as an `event loop server` thanks to the supported web servers: {{netty_server}}, {{jetty_server}} and {{undertow_server}}. Being {{netty_server}} the default web server.
+You can see {{jooby}} as an `event loop server` thanks to the supported web servers: {{netty_server}}, {{jetty_server}} and {{undertow_server}}. The default web server is {{netty_server}}.
 
 {{jooby}} isn't a traditional `thread server` where a HTTP request is bound to a thread.
 
 In {{jooby}} all the HTTP IO operations are performed in async & non blocking fashion. HTTP IO operations run in an IO thread (a.k.a event loop) while the application logic (your code) **always run in a worker thread**.
 
 ## worker threads
 
-The **worker thread** pool is provided by the web server: {{netty_server}}, {{jetty_server}} and {{undertow_server}}. To simplify application programming you can **block a worker thread**, for example you can safely run a **jdbc** query in a **worker thread**:
+The **worker thread** pool is provided by one of the supported web servers: {{netty_server}}, {{jetty_server}} or {{undertow_server}}. To simplify application programming you can **block a worker thread**, for example you can safely run a **jdbc** query in a **worker thread**:
 
 ```java
 {
@@ -22,11 +22,11 @@ The **worker thread** pool is provided by the web server: {{netty_server}}, {{je
 }
 ```
 
-Here the web server can accept as many connection it can (as its on non blocking) while the worker thread might blocks.
+The web server can accept as many connections it can (as its on non blocking) while the worker thread might block.
 
-Default worker thread pool is `20/100`. The correct/right size depends on your **business** and **work load** your application is suppose to handle. We suggest you to start with default setup and see how it goes, later you can reduce or increase the thread pool.
+The default worker thread pool is `20/100`. The optimal size depends on the **business** and **work load** your application is supposed to handle. It's recommended to start with the default setup and then tune the size of the thread pool if the need arises.
 
-In {{jooby}} we favor simplicity over complexity that is why your **code** can block, still there are more advanced setup that allow you to build async and reactive applications.
+{{jooby}} favors simplicity over complexity hence allowing your **code** to block. However, it also provides you with more advanced options that will allow you to build async and reactive applications.
 
 ## deferred
 
@@ -54,7 +54,7 @@ MVC API:
   }
 ```
 
-Previous examples are just `syntax sugar` for:
+The previous examples are just `syntactic sugar` for:
 
 ```
   return new Deferred(deferred -> {
@@ -66,7 +66,7 @@ Previous examples are just `syntax sugar` for:
   });
 ```
 
-There is more `syntax sugar` if you add the [AsyncMapper]({{defdocs}}/AsyncMapper.html) to your application:
+You can get more `syntactic sugar` if you add the [AsyncMapper]({{defdocs}}/AsyncMapper.html) to your application:
 
 Script API:
 
@@ -95,9 +95,9 @@ MVC API:
   }
 ```
 
-The [AsyncMapper]({{defdocs}}/AsyncMapper.html) convert `java.util.concurrent.Callable` and `java.util.concurrent.CompletableFuture` objects to {{deferred}} objects.
+The [AsyncMapper]({{defdocs}}/AsyncMapper.html) converts `java.util.concurrent.Callable` and `java.util.concurrent.CompletableFuture` objects to {{deferred}} objects.
 
-Another important thing to notice is that the deferred run in the **caller thread** (i.e. worker thread), so by default there is **no context switch** involve while running a {{deferred}} result:
+Another important thing to notice is that the deferred will run in the **caller thread** (i.e. worker thread), so by default there is **no context switch** involved in obtaining a {{deferred}} result:
 
 ```java
 {
@@ -111,15 +111,15 @@ Another important thing to notice is that the deferred run in the **caller threa
 }
 ```
 
-You might first see this as a bad thing, but is actually a good decision, because:
+This might not seem optimal at first, but there are some benefits to this:
 
-* It is super easy to setup a default executor (we will see how soon)
+* It makes it very easy to set up a default executor (this will be explained shortly)
 
-* Provides better integration with async & reactive libraries. A `direct` executor avoid the need of switching to a new thread and then probably dispatch (again) to a different thread provided by a library.
+* It provides better integration with async & reactive libraries. A `direct` executor avoids the need of switching to a new thread and then probably dispatch (again) to a different thread provided by a library.
 
 ## executor
 
-As we said before, the default executor run in the caller thread (a.k.a direct executor). Let's see how to override the default executor:
+As previously mentioned, the default executor runs in the caller thread (a.k.a direct executor). Let's see how to override the default executor:
 
 ```java
 {
@@ -131,7 +131,7 @@ As we said before, the default executor run in the caller thread (a.k.a direct e
 }
 ```
 
-Done! Now all our {{deferred}} result run in a `ForkJoinPool`. It also possible to specify an alternative executor:
+Done! Now all our {{deferred}} results run in a `ForkJoinPool`. It's also possible to specify an alternative executor:
 
 Script API:
 
@@ -175,7 +175,7 @@ import static org.jooby.Deferred.deferred;
   }
 ```
 
-Worth mention the [executor(ExecutorService)]({{defdocs}}/Jooby.html#executor-java.util.concurrent.ExecutorService-) methods automatically `shutdown` at application shutdown time.
+It's worth mentioning that the [executor(ExecutorService)]({{defdocs}}/Jooby.html#executor-java.util.concurrent.ExecutorService-) methods automatically `shutdown` at application shutdown time.
 
 ## promise
 
@@ -216,17 +216,17 @@ MVC API:
   }
 ```
 
-The **"promise"** version of {{deferred}} object is a key concept for integrating with external libraries.
+The **"promise"** version of the {{deferred}} object is a key concept for integrating with external libraries.
 
 ## advanced configuration
 
-Suppose you want to build a truly async application and after a **deep analysis** of your business you realize your application need to:
+Suppose you want to build a truly async application and after a **deep analysis** of your business demands you realize your application needs to:
 
 * Access a database
 * Call a remote service
 * Make a CPU intensive computation
 
-These are the 3 points where your application is suppose to block and wait for a result.
+These are the 3 points where your application is supposed to block and wait for a result.
 
 Let's start by reducing the **worker thread pool** to the number of **available processors**:
 
@@ -235,7 +235,7 @@ server.threads.Min = ${runtime.processors}
 server.threads.Max = ${runtime.processors}
 ```
 
-With this change, you need to be careful and **don't run blocking code** on routes anymore. Otherwise performance will be affected.
+With this change, you need to be careful to **avoid any blocking code** on routes, otherwise performance will suffer.
 
 Let's create a custom thread pool for each blocking access:
 
@@ -247,11 +247,11 @@ Let's create a custom thread pool for each blocking access:
 }
 ```
 
-For `database` access, we use a `cached` executor that will grow without a limit but free and release thread that are idle after `60s`.
+For `database` access, we use a `cached` executor which will grow without a limit but free and release threads that are idle after `60s`.
 
-For `remote` service, we use a `fixed` executor of `32` thread. The number here: `32` is just a random number for the purpose of the example.
+For `remote` service, we use a `fixed` executor of `32` threads. The number `32` is just a random number for the purpose of the example.
 
-For `intensive` computation, we use a `single` thread executor. Computation is too expensive and we want **one and only one** running at any time.
+For `intensive` computations, we use a `single` thread executor. Computation is too expensive and we want **one and only one** running at any time.
 
 ```java
 {
@@ -277,7 +277,7 @@ For `intensive` computation, we use a `single` thread executor. Computation is t
 }
 ```
 
-Here is the same example with [rx java](https://github.com/ReactiveX/RxJava):
+Here's the same example with [rx java](https://github.com/ReactiveX/RxJava):
 
 ```java
 {
@@ -314,14 +314,14 @@ Here is the same example with [rx java](https://github.com/ReactiveX/RxJava):
 }
 ```
 
-Main difference are:
+The main differences are:
 
-* we keep the default executor: `direct`. So we don't create a new thread and avoid context switching.
-* we use {{deferred}} object as `promise` and integrate with [rx java](https://github.com/ReactiveX/RxJava).
-* different thread pool semantic is done via [rx schedulers](http://reactivex.io/documentation/scheduler.html).
+* the default executor is kept `direct`. No new thread is created and context switching is avoided.
+* the {{deferred}} object is used as a `promise` and integrate with [rx java](https://github.com/ReactiveX/RxJava).
+* different thread pool semantics is achieved with the help of [rx schedulers](http://reactivex.io/documentation/scheduler.html).
 
-This is just one more example to demonstrate the value of the {{deferred}} object, because we provide an [rxjava](/doc/rxjava) module which takes care of binding {{deferred}} object into `Observables`.
+This is just another example to demonstrate the value of the {{deferred}} object, since a [rxjava](/doc/rxjava) module is provided which takes care of binding the {{deferred}} object into `Observables`.
 
-That's all about {{deferred}} object, it allows you to build async and reactive applications and at the same time: **keep it simple** (Jooby design goal).
+That sums up everything about the {{deferred}} object. It allows you to build async and reactive applications and at the same time: **keep it simple** (a Jooby design goal).
 
-Also, we invite you to checkout the available [async/reactive modules](/doc/async).
+You're also invited to check out the available [async/reactive modules](/doc/async).

md/available-modules.md

@@ -9,15 +9,15 @@
 * [gson](https://github.com/jooby-project/jooby/tree/master/jooby-gson): JSON supports via Gson.
 
 ## template engines
-* [handlebars/mustache](https://github.com/jooby-project/jooby/tree/master/jooby-hbs): logic less and semantic Mustache templates.
+* [handlebars/mustache](https://github.com/jooby-project/jooby/tree/master/jooby-hbs): logic-less and semantic Mustache templates.
 * [freemarker](https://github.com/jooby-project/jooby/tree/master/jooby-ftl): render templates with FreeMarker.
 
 ## session
-* [redis](https://github.com/jooby-project/jooby/tree/master/jooby-jedis/#redis-session-store): HTTP session on {{redis}}.
-* [memcached](https://github.com/jooby-project/jooby/tree/master/jooby-spymemcached/#session-store): HTTP session on {{memcached}}.
-* [mongodb](https://github.com/jooby-project/jooby/tree/master/jooby-mongodb/#mongodb-session-store): HTTP session on {{mongodb}}.
-* [hazelcast](https://github.com/jooby-project/jooby/tree/master/jooby-hazelcast/#session-store): HTTP session on {{hazelcast}}.
-* [ehcache](https://github.com/jooby-project/jooby/tree/master/jooby-ehcache/#session-store): HTTP session on {{ehcache}}.
+* [redis](https://github.com/jooby-project/jooby/tree/master/jooby-jedis/#redis-session-store): HTTP session store for {{redis}}.
+* [memcached](https://github.com/jooby-project/jooby/tree/master/jooby-spymemcached/#session-store): HTTP session store for {{memcached}}.
+* [mongodb](https://github.com/jooby-project/jooby/tree/master/jooby-mongodb/#mongodb-session-store): HTTP session store for {{mongodb}}.
+* [hazelcast](https://github.com/jooby-project/jooby/tree/master/jooby-hazelcast/#session-store): HTTP session store for {{hazelcast}}.
+* [ehcache](https://github.com/jooby-project/jooby/tree/master/jooby-ehcache/#session-store): HTTP session store for {{ehcache}}.
 
 ## sql
 * [jdbc](https://github.com/jooby-project/jooby/tree/master/jooby-jdbc): high performance connection pool for jdbc via {{hikari}}.

md/capsule.md

@@ -24,7 +24,7 @@ The ```capsule``` Maven profile is activated by the presence of the ```src/etc/c
 
 ## options
 
-Integration provides some defaults, which are listed here:
+The integration provides the following defaults:
 
 ```xml
 <properties>