Small language changes

Author: hansjorg

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/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 suppose to handle. We suggest you to start with the default setup and see how it goes, later you can reduce or increase the thread pool.
 
-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.
+In {{jooby}} we favor simplicity over complexity that is why your **code** can block, still there are more advanced options that 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 run in the **caller thread** (i.e. worker thread), so by default there is **no context switch** involved while running 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:
+You might see this as a bad thing at first, but it's actually a good decision, because:
 
 * It is super easy to setup a default executor (we will see how soon)
 
 * 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.
 
 ## 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,7 +216,7 @@ 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
 
@@ -226,7 +226,7 @@ Suppose you want to build a truly async application and after a **deep analysis*
 * 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**:
 
@@ -247,9 +247,9 @@ 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 that 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 here: `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.
 
@@ -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).
 
 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`.
 
-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/conf.md

@@ -1,8 +1,8 @@
 # conf, env and logging
 
-Jooby delegates configuration management to [Config library](https://github.com/typesafehub/config).
+Jooby delegates configuration management to the [Config library](https://github.com/typesafehub/config).
 
-By defaults Jooby expects to find an ```application.conf``` file at the root of classpath. You can find the `.conf` file under `conf` classpath directory.
+By defaults Jooby expects to find an ```application.conf``` file at the root of classpath. You can find the `.conf` file under the `conf` classpath directory.
 
 ## getting properties
 
@@ -59,7 +59,7 @@ Automatic type conversion is provided when a type:
 
 6) Has a static method **forName** that accepts a single **String** argument. Like ```java.nio.charset.Charset```
 
-You're free to inject the entirely ```com.typesafe.config.Config``` object or `sub-path/tree` of it.
+You're free to inject the entire ```com.typesafe.config.Config``` object or `sub-path/tree` of it.
 
 ## environment
 
@@ -69,7 +69,7 @@ This special property is represented at runtime with the [Env]({{apidocs}}/org/j
 
 For example: a module might decided to create a connection pool, cache, etc when ```application.env``` isn't set to `dev`.
 
-The `application.env` property can be set as command line argument too:
+The `application.env` property can be set as command line argument as well:
 
 Using a `fat jar`:
 
@@ -80,9 +80,9 @@ Using [stork](/doc/stork):
 
     bin/myapp --start prod
 
-## turn on/off features
+## turning features on or off
 
-As described before the ```application.env``` property defines the environment where the application is being executed. It is possible to turn on/off specific features base on the application environment:
+As described before, the ```application.env``` property defines the environment where the application is being executed. It's possible to turn on/off specific features based on the application environment:
 
 ```java
 {
@@ -108,7 +108,7 @@ There is a `~` (complement) operator:
 }
 ```
 
-The ```environment callback``` has access to ```config``` object, see:
+The ```environment callback``` has access to the ```config``` object, see:
 
 ```java
 {
@@ -141,7 +141,7 @@ Here is the list of special properties available in Jooby:
 
 ## precedence
 
-Configuration files are loaded in the following order (first-listed are higher priority)
+Configuration files are loaded in the following order:
 
 * system properties
 * arguments properties
@@ -150,6 +150,8 @@ Configuration files are loaded in the following order (first-listed are higher p
 * ([application].[conf])?
 * [module].[conf]*
 
+The first occurence of a property will take precedence.
+
 ### system properties
 
 System properties can override any other property. A system property is set at startup time, like: 
@@ -188,7 +190,7 @@ The default `classpath conf` file: `application.conf`
 
 ### [module].[conf]
 
-A [Module]({{defdocs}}/Jooby.Module.html) might have define his own set of (default) properties via [Module.config]({{defdocs}}/Jooby.Module.html#config--) method.
+A [Module]({{defdocs}}/Jooby.Module.html) might have defined its own set of (default) properties via the [Module.config]({{defdocs}}/Jooby.Module.html#config--) method.
 
 ```java
 {
@@ -198,7 +200,7 @@ A [Module]({{defdocs}}/Jooby.Module.html) might have define his own set of (defa
 
 ### custom .conf
 
-As we said before, the default `conf` file is `application.conf`, but you can use any other name you want:
+As mentioned earlier, the default `conf` file is `application.conf`, but you can use whatever name you prefer:
 
 ```java
 {
@@ -228,7 +230,7 @@ As we said before, the default `conf` file is `application.conf`, but you can us
 }
 ```
 
-* Starting the application in `dev` produces `conf` tree similar to:
+* Starting the application in `dev` produces a `conf` tree similar to:
 
 ```
 .
@@ -241,7 +243,7 @@ As we said before, the default `conf` file is `application.conf`, but you can us
     └── ...
 ```
 
-* Starting the application in `prod` produces `conf` tree similar to:
+* Starting the application in `prod` produces a `conf` tree similar to:
 
 ```
 .