Tidy documentation

Author: olvlvl

docs/Responders.md

@@ -1,9 +1,11 @@
 # Responders
 
-A responder takes a request and returns a response. It's a simple concept that can be implemented in many ways, of
-which this package only provides the foundation.
+A responder takes a request and returns a response.
+It is a simple concept that can be implemented in many ways,
+of which this package only provides the foundation.
 
-This package only provides an implementation that delegates the response to a matching responder found by a provider.
+This package only provides an implementation that delegates the response to a matching responder
+found by a provider.
 The package [ICanBoogie/Routing][] provides more exciting implementations.
 
 ```php
@@ -22,10 +24,10 @@ $response = $responder->respond($request);
 
 [WithRecovery][] decorates another responder to provide an exception recovery mechanism.
 
-The exception thrown by the responder is caught and a [RecoverEvent][] is emitted. Third parties can
-use that event to provide a response or replace the exception.
+The exception thrown by the responder is caught, and a [RecoverEvent][] is emitted.
+Third parties can use that event to provide a response or replace the exception.
 
-The following example demonstrate how to decorate a responder:
+The following example demonstrates how to decorate a responder:
 
 ```php
 <?php
@@ -37,7 +39,7 @@ namespace ICanBoogie\HTTP;
 $responder_with_recovery = new Responder\WithRecovery($responder);
 ```
 
-The following example demonstrate how to recover [NotFound][] exceptions:
+The following example demonstrates how to recover [NotFound][] exceptions:
 
 ```php
 <?php
@@ -60,7 +62,7 @@ $events->attach(function (RecoverEvent $event, NotFound $target) {
 $responder_with_recovery = new Responder\WithRecovery($responder);
 ```
 
-Alternatively you can provide another exception to throw instead:
+Alternatively, you can provide another exception to throw instead:
 
 ```php
 <?php
@@ -81,17 +83,17 @@ $responder_with_recovery = new Responder\WithRecovery($responder);
 ```
 
 
-## Events around respond
+## Events around respond()
 
-[WithEvents][] decorates another responder to emit events around the `respond()` method.
+[WithEvent][] decorates another responder to emit events around the `respond()` method.
 
-- [BeforeRespondEvent][] is emitted before the `respond()` method. Listeners can use the event to
-  alter the request or provide a response. If a response is provided the `respond()` method is *not*
-  invoked.
-- [RespondEvent][] is emitted after the `respond()` method. Listeners can use the event to alter the
-  response.
+1. [BeforeRespondEvent][] is emitted before the `respond()` method.
+    Listeners can use the event to alter the request or provide a response.
+    If a response is provided the `respond()` method is NOT invoked.
+2. [RespondEvent][] is emitted after the `respond()` method.
+    Listeners can use the event to alter the response.
 
-The following example demonstrate how to decorate a responder:
+The following example demonstrates how to decorate a responder:
 
 ```php
 <?php
@@ -103,7 +105,7 @@ namespace ICanBoogie\HTTP;
 $responder_with_events = new Responder\WithEvents($responder);
 ```
 
-The following example demonstrate how to attach listeners:
+The following example demonstrates how to attach listeners:
 
 ```php
 <?php
@@ -128,3 +130,6 @@ $events->attach(function (RespondEvent $event) {
 [WithRecovery]: ../lib/Responder/WithRecovery.php
 [RecoverEvent]: ../lib/RecoverEvent.php
 [NotFound]: ../lib/NotFound.php
+[WithEvent]: ../lib/Responder/WithEvent
+[BeforeRespondEvent]: ../lib/Responder/WithEvent/BeforeRespondEvent.php
+[RespondEvent]: ../lib/Responder/WithEvent/RespondEvent.php