Merge pull request #38 from benlongo/doc-cleanup

Grammatical issues in example and extra docs

src/doc/docs/examples/authentication.md

@@ -45,17 +45,17 @@ public class OAuthDynamicFeature extends AuthDynamicFeature {
 }
 ```
 
-Class recognized with [jersey installer](../installers/jersey-ext.md#dynamicfeature).
+The class is automatically picked up by the [jersey installer](../installers/jersey-ext.md#dynamicfeature).
 `OAuthAuthenticator` and `OAuthAuthorizer` are simple guice beans (no special installation required).
 
-Constructor injection used to obtain required guice managed instances and then configure
+Constructor injection is used to obtain required guice managed instances and then configure
 authentication the same way as described in dropwizard docs.
 
-If auto configuration is enabled, then class will be resolved and installed automatically.
+If auto configuration is enabled, then the class will be resolved and installed automatically.
 
 ## Chained auth
 
-[Chained auth](http://www.dropwizard.io/1.1.0/docs/manual/auth.html#chained-factories) is useful to support different authentication schemes.
+[Chained auth](http://www.dropwizard.io/1.1.0/docs/manual/auth.html#chained-factories) can be used to support different authentication schemes.
 
 Integration approach is the same as in simple case:
 

src/doc/docs/examples/eventbus.md

@@ -5,15 +5,15 @@ Example of [guicey-eventbus](../extras/eventbus.md) extension usage.
 !!! note ""
     Example [source code](https://github.com/xvik/dropwizard-guicey-examples/tree/master/eventbus)
 
-[Eventbus extension](../extras/eventbus.md) used for:
+The [eventbus extension](../extras/eventbus.md) is used for:
 
 * automatic listeners registration
-* bind eventbus instance in guice context (for publication)
-* print available listeners to console
+* binding eventbus instance in guice context (for publication)
+* printing available listeners to console
 
 ## Configuration
 
-Additional dependency required:
+An additional dependency is required:
 
 ```groovy
 compile 'ru.vyarus.guicey:guicey-eventbus:0.2.1'
@@ -31,7 +31,7 @@ GuiceBundle.builder()
 
 ## Event
 
-Events are simple POJO. Create event classes with properties you need (or without everything):
+Events are simple POJOs. Create event classes with properties you need (or without everything):
 
 ```java
 public class FooEvent {
@@ -58,11 +58,11 @@ public class BarEvent extends BaseEvent {}
 ```
 
 !!! note ""
-    For simplicity using events without properties.
+    For simplicity, properties are omitted.
 
 ## Publication
 
-Inject eventbus instance for publication:
+Inject the eventbus instance to enable publication:
 
 ```java
 @Inject EventBus eventbus;
@@ -75,7 +75,7 @@ public void someAction() {
 
 ## Listening
 
-Listener method must be annotated with `@Subscribe` and contain only one parameter (target event type):
+Listener methods must be annotated with `@Subscribe` and contain only one parameter of the target event type:
 
 ```java
 @Subscribe
@@ -87,8 +87,8 @@ public void onMultipleEvents(BaseEvent event) {}
 ```
 
 !!! attention
-    Listener method will be registered only for "known" guice beans. That means any extension
+    Listener methods will only be registered for "known" guice beans. That means any extension
     or manually declared guice bean (using module) or bean created with guice AOT (because it's declared
     as dependency for other bean) will be searched for listener methods.
 
-See [complete example](https://github.com/xvik/dropwizard-guicey-examples/tree/master/eventbus)         
+See [a complete example](https://github.com/xvik/dropwizard-guicey-examples/tree/master/eventbus)         

src/doc/docs/examples/governator.md

@@ -17,7 +17,7 @@ public class GovernatorInjectorFactory implements InjectorFactory {
 }
 ```
 
-Configure new factory in guice bundle:
+Configure the new factory in the guice bundle:
 
 ```java
 @Override
@@ -66,8 +66,8 @@ public class GovernatorLifecycle implements Managed {
 
 ```
 
-Guicey will find this managed bean, create governator injector (using custom factory), create managed bean instance and register it in dropwizard. 
-This will "bind" governator lifecycle to dropwizard lifecycle.
+Guicey will find this managed bean, create governator injector (using a custom factory), create a managed bean instance and register it in dropwizard. 
+This will "bind" the governator lifecycle to the dropwizard lifecycle.
 
 !!! note
-    If you need to run this managed before or after some other dropwizard managed use guicey [@Order annotation](../guide/ordering.md). 
+    If you need to control the order which the managed beans are started, use the [@Order annotation](../guide/ordering.md). 

src/doc/docs/examples/hibernate.md

@@ -35,7 +35,7 @@ public class HbnBundle extends HibernateBundle<HbnAppConfiguration> {
 ```
 
 !!! note
-    All model classes are configured inside constructor: `#!java super(Sample.class);`
+    All model classes are configured inside the constructor: `#!java super(Sample.class);`
 
 Configuration class:
 

src/doc/docs/examples/jdbi.md

@@ -6,13 +6,13 @@ Example of [guicey-jdbi](../extras/jdbi.md) extension usage.
     Example [source code](https://github.com/xvik/dropwizard-guicey-examples/tree/master/jdbi)
 
 
-[JDBI extension](../extras/jdbi.md) used for:
+The [JDBI extension](../extras/jdbi.md) allows:
 
 * using jdbi proxies as guice beans
-* be able to use injection inside proxies
-* be able to use AOP on proxies
-* use annotations for transaction definition
-* automatic repositories and mapper installation
+* using injection inside proxies
+* using AOP on proxies
+* using annotations for transaction definition
+* automatic repository and mapper installation
 
 ## Configuration
 
@@ -43,7 +43,7 @@ public class JdbiAppConfiguration extends Configuration {
 }
 ```
 
-For simplicity, embedded H2 database used:
+For simplicity, an embedded H2 database is used:
 
 ```yaml
 database:
@@ -83,7 +83,7 @@ GuiceBundle.builder()
 ## Repository definition
 
 !!! warning
-    All jdbi repositories must be annotated with `@JdbiRepository` to let [repository installer](../extras/jdbi.md#repository)
+    All jdbi repositories must be annotated with `@JdbiRepository` to let the [repository installer](../extras/jdbi.md#repository)
     recognize and properly install them.
 
 ```java
@@ -153,10 +153,10 @@ public abstract class Crud<T extends IdEntity> {
 !!! note ""
     You don't necessarily need to use `Crud` - it's an advanced usage example.
 
-Repository is annotated with `@InTransaction` to allow using repositories directly: repository method call is the smallest transaction scope. 
-Transaction scope could be enlarged by using annotation on calling guice beans or 
-[declaring transaction manually](../extras/jdbi.md#manual-transaction-definition).
-In order to better understand how transactions work read [unit of work docs section](../extras/jdbi.md#unit-of-work).
+The repository is annotated with `@InTransaction` to allow direct usage; repository method calls are the smallest transaction scope. 
+The transaction scope can be enlarged by using annotations on calling guice beans or 
+[declaring transactions manually](../extras/jdbi.md#manual-transaction-definition).
+In order to better understand how transactions work, read the [unit of work docs section](../extras/jdbi.md#unit-of-work).
 
 !!! note
     `@InTransaction` is handled with guice AOP, so you can use any other guice aop related features.
@@ -186,15 +186,14 @@ public class UserMapper implements ResultSetMapper<User> {
 }
 ```
 
-Mappers are installed with [mapper installer](../extras/jdbi.md#result-set-mapper).
-If auto scan is enabled then all mappers will be detected automatically and registered in dbi instance.
-Mapper are instantiated as normal guice bean without restrictions: so you can use injection and aop 
+Mappers are installed with the [mapper installer](../extras/jdbi.md#result-set-mapper).
+If auto scan is enabled then all mappers will be detected automatically and registered in the dbi instance.
+Mappers are instantiated as normal guice beans without restrictions which means you can use injection and aop 
 (it's only not shown in example mapper).
 
 !!! note
-    Mapper installer mostly automates (and unifies) registration. If your mapper does not need to be guice bean
-    and you dont want to use auto configuration then you can register it manually in dbi instance 
-    (it's available for injection).
+    The mapper installer mostly automates (and unifies) registration. If your mapper does not need to be guice bean
+    and you dont want to use auto configuration then you can register it manually in dbi instance, making it available for injection.
 
 Also, see complementing binding annotation, used to bind object to query parameters:
 
@@ -249,12 +248,12 @@ public class UserResource {
 }
 ```
 
-`UserMapper` and `UserBind` are used implicitly to convert Pojo into db record and back.
+`UserMapper` and `UserBind` are used implicitly to convert the POJO into a db record and back.
 
 You can use `@InTransaction` on repository method to enlarge transaction scope, but, in contrast
 to hibernate you dont't have to always declare it to avoid lazy initialization exception 
-(because jdbi produce simple pojos).
+(because jdbi produces simple pojos).
 
 !!! note
-    `@InTrasaction` name was used to avoid confusion with commonly used `@Transactional` annotation.
-    You [can bind any annotation class](../extras/jdbi.md#intransaction) if you like to use different name (annotation is just a marker)
+    `@InTrasaction` is named to avoid confusion with the commonly used `@Transactional` annotation.
+    You [can bind any annotation class](../extras/jdbi.md#intransaction) if you like to use a different name (the annotation is just a marker)

src/doc/docs/extras/admin-rest.md

@@ -1,10 +1,10 @@
 # Admin REST
 
 All rest resources could be "published" in the admin context too.  This is just an emulation of rest: the same resources 
-are accessible in both contexts. On admin side special servlet simply redirects all incoming requests into jersey context.
+are accessible in both contexts. On admin side special servlet simply redirects all incoming requests into the jersey context.
 
-Such approach is better than registering completely separate jersey context for admin rest because
-of no overhead and simplicity of jersey extensions management.
+Such an approach is better than registering a completely separate jersey context for admin rest because
+of no overhead and the simplicity of jersey extensions management.
 
 ## Configuration
 
@@ -14,19 +14,19 @@ To install admin rest servlet, register bundle:
 bootstrap.addBundle(new AdminRestBundle());
 ```
 
-In this case rest is registered either to '/api/*', if main context rest is mapped to root ('/*')
+In this case, rest is registered either to '/api/*', if main context rest is mapped to root ('/*')
 or to the same path as main context rest.
 
-To register on custom path:
+To register on a custom path:
 
 ```java
 bootstrap.addBundle(new AdminRestBundle("/custom/*"));
 ```
 
 ## Security
 
-In order to hide specific resource methods or entire resources on main context, annotate resource methods
-or resource class with `@AdminResource` annotation.
+In order to hide specific resource methods or entire resources on the main context, annotate resource methods
+or resource classes with the `@AdminResource` annotation.
 
 For example:
 
@@ -39,7 +39,8 @@ public String admin() {
 }
 ```
 
-This (annotated) method will return 403 error when called from main context and process when called from admin context.
+This (annotated) method will return 403 error when called from main context, but should function normally 
+when called from the admin context.
 
 This is just the simplest option to control resources access. Any other method may be used (with some security
 framework or something else).

src/doc/docs/extras/eventbus.md

@@ -17,7 +17,7 @@ Features:
 [![JCenter](https://img.shields.io/bintray/v/vyarus/xvik/dropwizard-guicey-ext.svg?label=jcenter)](https://bintray.com/vyarus/xvik/dropwizard-guicey-ext/_latestVersion)
 [![Maven Central](https://img.shields.io/maven-central/v/ru.vyarus.guicey/guicey-eventbus.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/ru.vyarus.guicey/guicey-eventbus)
 
-Avoid version in dependency declaration below if you use [extensions BOM](bom.md). 
+Remove `version` in dependency declaration below if you using [the BOM extensions](bom.md). 
 
 Maven:
 
@@ -80,7 +80,7 @@ public class SomeOtherService {
 }
 ```
 
-After server start you should see all registered event listeners in log:
+After server start you should see all registered event listeners in the log:
 
 ```
 INFO  [2016-12-01 12:31:02,819] ru.vyarus.guicey.eventbus.report.EventsReporter: EventBus subscribers = 
@@ -92,9 +92,8 @@ INFO  [2016-12-01 12:31:02,819] ru.vyarus.guicey.eventbus.report.EventsReporter:
 
 !!! note 
     Only subscriptions of beans registered at the time of injector startup will be shown.
-    For example, if MyBean has subscription method but binding for it not declared (and noone depends on it)
-    then JIT binding will be created only somewhere later in time (when bean will be actually used) and 
-    so listener registration happen after server startup and will not be shown in console report.
+    For example, if MyBean has a subscription method but a binding for it is not declared (and noone depends on it),
+    a JIT binding will be created later in time (when bean will be actually used) and will not be reflected in the logs. 
 
 ### Consuming multiple events
 
@@ -110,7 +109,7 @@ public void onEvent(Object event){
 
 ## Event bus 
 
-By default, events will be handled synchronously (`bus.push()` waits while all subscribers processed).
+By default, events will be handled synchronously (`bus.push()` waits while all subscribers process).
 
 If you want events to be async use custom eventbus:
 
@@ -120,7 +119,7 @@ new EventBusBundle(
 )
 ``` 
 
-By default, event listeners considered not thread safe and so no parallel events processing (for single method) 
+By default, event listeners are not considered thread safe and no parallel events processing (for single method) 
 will be performed. To mark subscriber as thread safe use `@AllowConcurrentEvents`:
 
 ```java
@@ -129,9 +128,9 @@ will be performed. To mark subscriber as thread safe use `@AllowConcurrentEvents
 public void onEvent(MyEvent event)      
 ```
 
-If listener method will fail to process event (throw exception) then other listeners will still be processed
-and failed listener exception will be logged. If you want to change this behaviour set custom exception 
-handler by creating custom eventbus instance:
+If a listener method fails to process an event (throws an exception), then other listeners will still be processed
+and the exception will be logged. If you want to change this behaviour, set a custom exception 
+handler by creating a custom eventbus instance:
 
 ```java
 new EventBusBundle(
@@ -141,21 +140,17 @@ new EventBusBundle(
 
 ## Listeners recognition
 
-Guice type listener used to intercept all beans instances. Each bean instance is registered in eventbus: 
-it's valid behaviour for eventbus and only beans with actual listener methods will be registered.
-
-But, it means that each bean class is checked: every method in class hierarchy. This is very fast and
-does not make problems for most of the cases. But, if you want, you can reduce the scope for checking by
-specifying custom class matcher:
+The guice type listener is used to intercept _all_ bean instances and thus looks at every method in the 
+class hierarchy; however, only beans that actually have `@Subscribe`rs will be registered with the event bus. 
+This process is fast and usually causes no issues. If needed, you can reduce the scope with a 
+custom class matcher:
 
 ```java
 new EventBusBundle()
     .withMatcher(Matchers.inSubpackage("some.package"))
 ```
 
-This will only check beans in class and subpackages.
-
-If you want maximum performance, then you can add extra marker annotation (e.g. `@HasEvents`) and reduce
+If you want maximum performance, then you can add a marker annotation (e.g. `@HasEvents`) and reduce
 scope to just annotated classes:
 
 ```java
@@ -166,19 +161,17 @@ new EventBusBundle()
 
 ## Console reporting
 
-You can switch off console reporting (for example, if you have too much listeners):
+You can switch off console reporting (for example, if you have too many listeners):
 
 ```java
 new EventBusBundle().noReport()
 ```
 
-Important moment: reporting has to use reflection to get subscribers list. If reflection will fail with newer guava version
-(not yet supported), then simply disable reporting and everything will work.
+!!! note
+    Reporting has to use reflection to get subscribers list. If this fails with a newer guava version
+    (not yet supported), then simply disable reporting and everything will work as expected.
 
 ## Subscribers info bean
-
-Special guice bean registered and available for injection: `EventSubscribersInfo`.
-With it you can get active listeners and used event types. Reporting use it for console report.
-It may be useful for unit tests.
-
-As described above, internally it use reflection to access eventbus listeners map. 
+`EventSubscribersInfo` is a registered (available for injection) bean that provides active listeners
+and used event types. As described above, it uses reflection internally to access the eventbus listeners map. 
+It may be useful for testing. 

src/doc/docs/guide/bindings.md

@@ -7,7 +7,7 @@ Also, guicey binds some dropwizard and jersey objects.
 
 ## Configuration
 
-`Configuration` bound to guice as:
+`Configuration` bound to guice as: 
 
 * `io.dropwizard.Configuration`
 * Your configuration class (`#!java MyConfiguration extends Configuration`)