[#18] Reviewed and edited

Author: weierophinney

README.md

@@ -8,9 +8,8 @@ Introduction
 
 This module provides data structures and rendering for the API-Problem format.
 
-- [Problem API](http://tools.ietf.org/html/draft-nottingham-http-problem-05),
-  used for reporting API problems
-
+- [Problem Details for HTTP APIs](http://tools.ietf.org/html/draft-nottingham-http-problem-06),
+  used for reporting API problems.
 
 Installation
 ------------
@@ -80,7 +79,7 @@ function:
         'ZF\ApiProblem\Listener\SendApiProblemResponseListener' => 'ZF\ApiProblem\Factory\SendApiProblemResponseListenerFactory',
         'ZF\ApiProblem\View\ApiProblemRenderer'                 => 'ZF\ApiProblem\Factory\ApiProblemRendererFactory',
         'ZF\ApiProblem\View\ApiProblemStrategy'                 => 'ZF\ApiProblem\Factory\ApiProblemStrategyFactory',
-    )
+    ),
 ),
 'view_manager' => array(
     // Enable this in your application configuration in order to get full
@@ -98,40 +97,42 @@ ZF2 Events
 
 The `ApiProblemListener` attaches to three events in the MVC lifecycle:
 
-- `MvcEvent::EVENT_RENDER` with a priority of 1000
-- `MvcEvent::EVENT_DISPATCH_ERROR` with a priority of 100
-- `MvcEvent::EVENT_DISPATCH` as a _shared_ event on `Zend\Stdlib\DispatchableInterface` with a
-  priority of 100
+- `MvcEvent::EVENT_DISPATCH` as a _shared_ listener on `Zend\Stdlib\DispatchableInterface` with a
+  priority of `100`.
+- `MvcEvent::EVENT_DISPATCH_ERROR` with a priority of `100`.
+- `MvcEvent::EVENT_RENDER` with a priority of `1000`.
 
-If the current Accept media type does not match the configured api-problem media types,
-then this listener passes on taking any action.
+If the current `Accept` media type does not match the configured API-Problem media types (by
+default, these are `application/json` and `application/*+json`), then this listener returns without
+taking any action.
 
 When this listener does take action, the purposes are threefold:
 
 - Before dispatching, the `render_error_controllers` configuration value is consulted to determine
-  if the `ZF\ApiProblem\Listener\RenderErrorListener` should be attached, see
-  `RenderErrorListener` for more information.
-- After dispatching, detect the type of response from the controller, if it is already an
-  ApiProblem model, continue.  If not, but there was an exception throw during dispatch,
-  convert the response to an api-problem with some information as to what the exception is.
-- If a dispatch error has occurred, and is a valid Accept type, attempt to cast the dispatch
-  exception into an API problem response.
+  if the `ZF\ApiProblem\Listener\RenderErrorListener` should be attached; see
+  [RenderErrorListener](#rendererrorlistener) for more information.
+- After dispatching, detects the type of response from the controller; if it is already an
+  `ApiProblem` model, it continues without doing anything. If an exception was thrown during
+  dispatch, it converts the response to an API-Problem response with some information from the
+  exception.
+- If a dispatch error occurred, and the `Accept` type is in the set defined for API-Problems, it
+  attempts to cast the dispatch exception into an API-Problem response.
 
 #### `ZF\ApiProblem\Listener\RenderErrorListener`
 
-This listener is attached to `MvcEvent::EVENT_RENDER_ERROR` at priority `100`.  This listener
-is conditionally attached by `ZF\ApiProblem\Listener\ApiProblemListener` for controllers that
-require API Problem responses.  With a priority of `100`, this ensures that this Render Error
-time listener will run before the ZF2 one.  In cases when it does run, it will attempt to
-take exceptions and inject an api-problem response in the HTTP response.
+This listener is attached to `MvcEvent::EVENT_RENDER_ERROR` at priority `100`.  This listener is
+conditionally attached by `ZF\ApiProblem\Listener\ApiProblemListener` for controllers that require
+API Problem responses.  With a priority of `100`, this ensures that this listener runs before the
+default ZF2 listener on this event. In cases when it does run, it will cast an exception into an
+API-problem response.
 
 #### `ZF\ApiProblem\Listener\SendApiProblemResponseListener`
 
-This listener is attached to the `SendResponseEvent::EVENT_SEND_RESPONSE` at priority `-500`.
-The primary purpose of this listener is to, when an ApiProblem response is to be sent, to
-send the headers and content body.  This differs from the way ZF2 typically sends responses
-in that inside this listener it takes into account if the Response should include an
-exception trace as part of the serialized response or not.
+This listener is attached to `SendResponseEvent::EVENT_SEND_RESPONSE` at priority `-500`.  The
+primary purpose of this listener is, on detection of an API-Problem response, to send appropriate
+headers and the problem details as the content body. If the `view_manager`'s `display_exceptions`
+setting is enabled, the listener will determine if the API-Problem represents an application
+exception, and, if so, inject the exception trace as part of the serialized response.
 
 ZF2 Services
 ------------
@@ -146,56 +147,73 @@ ZF2 Services
 
 #### `ZF\ApiProblem\View\ApiProblemRenderer`
 
-This service extends the JsonRenderer service from the ZF2 MVC layer.  It's primary responsibility
+This service extends the `JsonRenderer` service from the ZF2 MVC layer.  Its primary responsibility
 is to decorate JSON rendering with the ability to optionally output stack traces.
 
 #### `ZF\ApiProblem\View\ApiProblemStrategy`
 
-This service is a view strategy that allows any ApiProblemModels details to be injected into the
-MVC's HTTP response object.  This is similar in nature to the `JsonStrategy`.
+This service is a view strategy that detects a `ZF\ApiProblem\View\ApiProblemModel`; when detected,
+it selects the [ApiProblemRender](#zfapiproblemviewapiproblemrenderer), and injects the response
+with a `Content-Type` header that contains the `application/problem+json` media type. This is
+similar in nature to Zend Framework 2's `JsonStrategy`.
 
 ### Models
 
 #### `ZF\ApiProblem\ApiProblem`
 
-An instance of `ZF\ApiProblem\ApiProblem` serves the purpose of modeling the kind of problem that
-is encountered.  An instance of `ApiProblem` is typically wrapped in an `ApiProblemResponse`
-(see `ApiProblemResponse` below).  Most information can be passed into the constructor:
+An instance of `ZF\ApiProblem\ApiProblem` serves the purpose of modeling the kind of problem that is
+encountered.  An instance of `ApiProblem` is typically wrapped in an
+[ApiProblemResponse](#zfapiproblemapiproblemresponse). Most information can be passed into the
+constructor:
 
 ```php
 class ApiProblem {
-  public function __construct($status, $detail, $type = null, $title = null, array $additional = array()) {}
+    public function __construct(
+        $status,
+        $detail,
+        $type = null,
+        $title = null,
+        array $additional = array()
+    ) {
+        /* ... */
+    }
 }
 ```
 
 For example:
 
 ```php
 new ApiProblem(404, 'Entity not found');
+
 // or
+
 new ApiProblem(424, $exceptionInstance);
 ```
 
 #### `ZF\ApiProblem\ApiProblemResponse`
 
-An instance of `ZF\ApiProblem\ApiProblem` can be returned from any controller service or ZF2
-MVC event.  When it is, the HTTP response will be converted to the proper JSON based HTTP response.
+An instance of `ZF\ApiProblem\ApiProblemResponse` can be returned from any controller service or ZF2
+MVC event in order to short-circuit the MVC lifecycle and immediately return a response. When it
+is, the response will be converted to the proper JSON structure for an API-Problem, and the
+`Content-Type` header will be set to the `application/problem+json` media type.
 
 For example:
 
 ```php
+use Zend\Mvc\Controller\AbstractActionController;
 use ZF\ApiProblem\ApiProblem;
 use ZF\ApiProblem\ApiProblemResponse;
-class MyController extends Zend\Mvc\Controller\AbstractActionController
+
+class MyController extends AbstractActionController
 {
     /* ... */
     public function fetch($id)
     {
         $entity = $this->model->fetch($id);
-        if (!$entity) {
+        if (! $entity) {
             return new ApiProblemResponse(ApiProblem(404, 'Entity not found'));
         }
         return $entity;
     }
 }
-```
+```