From aec8bcca4a887129788d1712636de4754587a836 Mon Sep 17 00:00:00 2001
From: PJ Dietz <pjdietz@gmail.com>
Date: Sun, 13 Jul 2014 10:12:12 -0400
Subject: [PATCH] Fix phpdoc for interfaces, Handler.

---
 phpdoc.dist.xml                               |  2 +-
 src/pjdietz/WellRESTed/Handler.php            | 10 ++---
 .../Interfaces/HandlerInterface.php           |  8 ++--
 .../Interfaces/RequestInterface.php           | 33 +++++++++++----
 .../Interfaces/ResponseInterface.php          | 42 +++++++++++++++----
 5 files changed, 70 insertions(+), 25 deletions(-)

diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml
index 3595b64..84a5403 100644
--- a/phpdoc.dist.xml
+++ b/phpdoc.dist.xml
@@ -12,7 +12,7 @@
         <target>docs</target>
     </transformer>
     <transformations>
-        <template name="clean" />
+        <template name="responsive" />
     </transformations>
     <files>
         <directory>src</directory>
diff --git a/src/pjdietz/WellRESTed/Handler.php b/src/pjdietz/WellRESTed/Handler.php
index e994f97..71f94a0 100644
--- a/src/pjdietz/WellRESTed/Handler.php
+++ b/src/pjdietz/WellRESTed/Handler.php
@@ -19,11 +19,11 @@ use pjdietz\WellRESTed\Interfaces\RequestInterface;
  * Responds to a request based on the HTTP method.
  *
  * To use Handler, create a subclass and implement the methods for any HTTP
- * verbs you would like to support. (`get()` for GET, `post()` for POST, etc).
- *
- * - Access the request via the protected member `$this->request`
- * - Access a map of arguments via `$this->args` (e.g., URI path variables)
- * - Modify `$this->response` to provide the response the instance will return
+ * verbs you would like to support. (get() for GET, post() for POST, etc).
+ * <br /><br />
+ * - Access the request via the protected member $this->request<br />
+ * - Access a map of arguments via $this->args (e.g., URI path variables)<br />
+ * - Modify $this->response to provide the response the instance will return<br />
  */
 abstract class Handler implements HandlerInterface
 {
diff --git a/src/pjdietz/WellRESTed/Interfaces/HandlerInterface.php b/src/pjdietz/WellRESTed/Interfaces/HandlerInterface.php
index 34d2532..ae170c3 100644
--- a/src/pjdietz/WellRESTed/Interfaces/HandlerInterface.php
+++ b/src/pjdietz/WellRESTed/Interfaces/HandlerInterface.php
@@ -16,9 +16,11 @@ namespace pjdietz\WellRESTed\Interfaces;
 interface HandlerInterface {
 
     /**
-     * @param RequestInterface $request The request to build a response for.
-     * @param array|null $args Optional map of arguments.
-     * @return ResponseInterface|null A response, or null if this handler will not handle.
+     * Return the handled response.
+     *
+     * @param RequestInterface $request The request to respond to.
+     * @param array|null $args Optional additional arguments.
+     * @return ResponseInterface The handled response.
      */
     public function getResponse(RequestInterface $request, array $args = null);
 
diff --git a/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php b/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php
index 354dc5c..1770306 100644
--- a/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php
+++ b/src/pjdietz/WellRESTed/Interfaces/RequestInterface.php
@@ -15,24 +15,43 @@ namespace pjdietz\WellRESTed\Interfaces;
  */
 interface RequestInterface
 {
-    /** @return string  HTTP request method (e.g., GET, POST, PUT). */
+    /**
+     * Return the HTTP verb (e.g., GET, POST, PUT).
+     *
+     * @return string Request verb
+     */
     public function getMethod();
 
-    /** @return string  Path component of the request URI */
+    /**
+     * Return path component of the request URI.
+     *
+     * @return string Path component
+     */
     public function getPath();
 
-    /** @return array  Query paramters as key-value pairs */
+    /**
+     * Return an associative array of query paramters.
+     *
+     * @return array Query paramters
+     */
     public function getQuery();
 
     /**
-     * Return the value for this header name
+     * Return the value for a given header.
      *
-     * @param $headerName
-     * @return string $headerName
+     * Per RFC 2616, HTTP headers are case-insensitive. Take care to conform to
+     * this when implementing.
+     *
+     * @param string $headerName Field name of the header
+     * @return string Header field value
      */
     public function getHeader($headerName);
 
-    /** @return string  Requst body */
+    /**
+     * Return the body of the request.
+     *
+     * @return string Request body
+     */
     public function getBody();
 
 }
diff --git a/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php b/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php
index d4c4792..446ba6f 100644
--- a/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php
+++ b/src/pjdietz/WellRESTed/Interfaces/ResponseInterface.php
@@ -15,30 +15,54 @@ namespace pjdietz\WellRESTed\Interfaces;
  */
 interface ResponseInterface
 {
-    /** @return int  HTTP status code */
+    /**
+     * Return the HTTP status code
+     *
+     * @return int HTTP status code
+     */
     public function getStatusCode();
 
-    /** @param int $statusCode  HTTP status code */
+    /**
+     * Set the status code for the response.
+     *
+     * @param int $statusCode HTTP status code
+     */
     public function setStatusCode($statusCode);
 
     /**
-     * Return the value for this header name
+     * Return the value for a given header.
      *
-     * @param $headerName
-     * @return string $headerName
+     * Per RFC 2616, HTTP headers are case-insensitive. Take care to conform to
+     * this when implementing.
+     *
+     * @param string $headerName Field name of the header
+     * @return string Header field value
      */
     public function getHeader($headerName);
 
     /**
-     * @param string $headerName
-     * @param string $headerValue
+     * Set the value for a given header.
+     *
+     * Per RFC 2616, HTTP headers are case-insensitive. Take care to conform to
+     * this when implementing.
+     *
+     * @param string $headerName Field name
+     * @param string $headerValue Field value
      */
     public function setHeader($headerName, $headerValue);
 
-    /** @return string */
+    /**
+     * Return the body of the response.
+     *
+     * @return string Response body
+     */
     public function getBody();
 
-    /** @param string $body */
+    /**
+     * Set the body of the response.
+     *
+     * @param string $body Response body
+     */
     public function setBody($body);
 
     /** Issue the reponse to the client. */