From acc5b4831400cb765f035cdd06020055c544f2d6 Mon Sep 17 00:00:00 2001
From: PJ Dietz <pjdietz@gmail.com>
Date: Sun, 7 Jun 2015 09:42:49 -0400
Subject: [PATCH] Update docs for messages to include section on response
 status codes.

---
 docs/source/messages.rst | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/source/messages.rst b/docs/source/messages.rst
index 7d1f78d..8f2b8af 100644
--- a/docs/source/messages.rst
+++ b/docs/source/messages.rst
@@ -197,8 +197,8 @@ The JSON example cast the stream to a string, but we can also do things like cop
 
     }
 
-Paramters
-^^^^^^^^^
+Parameters
+^^^^^^^^^^
 
 PSR-7_ eliminates the need to read from many of the superglobals. We already saw how ``getParsedBody`` takes the place of reading directly from ``$_POST`` and ``getQueryParams`` replaces reading from ``$_GET``. Here are some other ``ServerRequestInterface`` methods with **brief** descriptions. Please see PSR-7_ for full details, particularly for ``getUploadedFiles``.
 
@@ -365,6 +365,30 @@ Chain multiple ``with`` methods together fluently:
         ->withHeader("Content-type", "text/plain")
         ->withBody(new \WellRESTed\Message\Stream("Hello, world!);
 
+Status
+^^^^^^
+
+Provide the status code for your response with the ``withStatus`` method. When you pass a standard status code to this method, the WellRESTed response implementation will provide an appropriate reason phrase for you. For a list of reason phrases provided by WellRESTed, see the IANA `HTTP Status Code Registry`_.
+
+.. note::
+
+    The "reason phrase" is the text description of the status that appears in the status line of the response. The "status line" is the very first line in the response that appears before the first header.
+
+
+Although the PSR-7_ ``ResponseInterface::withStatus`` method accepts the reason phrase as an optional second parameter, you generally shouldn't pass anything unless you are using a non-standard status code. (And you probably shouldn't be using a non-standard status code.)
+
+.. code-block:: php
+
+    // Set the status and view the reason phrase provided.
+
+    $response = $response->withStatus(200);
+    $response->getReasonPhrase();
+    // "OK"
+
+    $response = $response->withStatus(404);
+    $response->getReasonPhrase();
+    // "Not Found"
+
 Headers
 ^^^^^^^
 
@@ -490,6 +514,7 @@ Each PSR-7_ message MUST have a body, so there's no ``withoutBody`` method. You
 
     }
 
+.. _HTTP Status Code Registry: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
 .. _PSR-7: http://www.php-fig.org/psr/psr-7/
 .. _Getting Started: getting-started.html
 .. _Middleware: middleware.html