Updates to documentation for better documentation generation

Refactored WellrestedException to WellRESTedException

src/pjdietz/WellRESTed/Exceptions/CurlException.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Exceptions\CurlException
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -12,6 +14,6 @@ namespace pjdietz\WellRESTed\Exceptions;
  * Exception related to a cURL operation. The message and code should correspond
  * to the cURL error and error number that caused the excpetion.
  */
-class CurlException extends WellrestedException
+class CurlException extends WellRESTedException
 {
 }

src/pjdietz/WellRESTed/Exceptions/WellRESTedException.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Exceptions\WellRESTedException
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -13,6 +15,6 @@ use \Exception;
 /**
  * Top level class for custom exceptions thrown by Well RESTed.
  */
-class WellrestedException extends Exception
+class WellRESTedException extends Exception
 {
 }

src/pjdietz/WellRESTed/Handler.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Handler
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -11,7 +13,7 @@ namespace pjdietz\WellRESTed;
 /**
  * A Handler issues a response for a given resource.
  *
- * @property-read Response response  The Response to the request
+ * @property-read Response response The Response to the request
  */
 class Handler
 {
@@ -56,9 +58,11 @@ class Handler
     }
 
     // -------------------------------------------------------------------------
-    // !Accessors
+    // Accessors
 
     /**
+     * Magic function for properties
+     *
      * @param string $propertyName
      * @return mixed
      */
@@ -71,6 +75,8 @@ class Handler
     }
 
     /**
+     * Return the instance's Reponse
+     *
      * @return Response
      */
     public function getResponse()
@@ -119,7 +125,7 @@ class Handler
     }
 
     // -------------------------------------------------------------------------
-    // !HTTP Methods
+    // HTTP Methods
 
     // Each of these methods corresponds to a standard HTTP method. Each method
     // has no arguments and returns nothing, but should affect the instance's

src/pjdietz/WellRESTed/Message.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Message
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -56,9 +58,11 @@ abstract class Message
     protected $protocolVersion = '1.1';
 
     // -------------------------------------------------------------------------
-    // !Accessors
+    // Accessors
 
     /**
+     * Magic accessor method
+     *
      * @param string $propertyName
      * @return mixed
      */
@@ -71,6 +75,8 @@ abstract class Message
     }
 
     /**
+     * Magic accessor method
+     *
      * @param string $propertyName
      * @param $value
      */
@@ -83,6 +89,8 @@ abstract class Message
     }
 
     /**
+     * Magic accessor method
+     *
      * @param string $propertyName
      * @return mixed
      */
@@ -95,6 +103,8 @@ abstract class Message
     }
 
     /**
+     * Magic accessor method
+     *
      * @param string $propertyName
      */
     public function __unset($propertyName)
@@ -126,6 +136,8 @@ abstract class Message
     }
 
     /**
+     * Return if the body is set
+     *
      * @return bool
      */
     public function issetBody()
@@ -133,6 +145,9 @@ abstract class Message
         return isset($this->body);
     }
 
+    /**
+     * Unset the body property
+     */
     public function unsetBody()
     {
         unset($this->body);
@@ -246,6 +261,8 @@ abstract class Message
     }
 
     /**
+     * Return the protocol (e.g., HTTP)
+     *
      * @return string
      */
     public function getProtocol()
@@ -278,6 +295,8 @@ abstract class Message
     }
 
     /**
+     * Return if the protocol property is set.
+     *
      * @return bool
      */
     public function issetProtocol()
@@ -285,12 +304,17 @@ abstract class Message
         return isset($this->protocol);
     }
 
+    /**
+     * Unset the protocol property.
+     */
     public function unsetProtocol()
     {
         unset($this->protocol);
     }
 
     /**
+     * Return the version portion of the protocol. For HTTP/1.1, this is 1.1
+     *
      * @return string
      */
     public function getProtocolVersion()
@@ -299,6 +323,8 @@ abstract class Message
     }
 
     /**
+     * Assign a new protocol version
+     *
      * @param string $protocolVersion
      */
     public function setProtocolVersion($protocolVersion)
@@ -307,6 +333,8 @@ abstract class Message
     }
 
     /**
+     * Return if the version portion of the protocol is set.
+     *
      * @return bool
      */
     public function issetProtocolVersion()
@@ -314,6 +342,9 @@ abstract class Message
         return isset($this->protocolVersion);
     }
 
+    /**
+     * Unset the version portion of the protocol.
+     */
     public function unsetProtocolVersion()
     {
         unset($this->protocolVersion);

src/pjdietz/WellRESTed/Request.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Request
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -26,8 +28,6 @@ namespace pjdietz\WellRESTed;
  * @property-read string pathParts  Fragments of the path, delimited by slashes
  * @property array query  Associative array of query parameters
  * @property array uri  Full URI (protocol, hostname, path, etc.)
- *
- * @package WellRESTed
  */
 class Request extends Message
 {
@@ -75,9 +75,11 @@ class Request extends Message
     static protected $theRequest;
 
     // -------------------------------------------------------------------------
-    // !Accessors
+    // Accessors
 
     /**
+     * Return the hostname portion of the URI
+     *
      * @return string
      */
     public function getHostname()
@@ -86,6 +88,8 @@ class Request extends Message
     }
 
     /**
+     * Assign the hostname portion of the URI
+     *
      * @param string $hostname
      */
     public function setHostname($hostname)
@@ -94,6 +98,8 @@ class Request extends Message
     }
 
     /**
+     * Return if the hostname portion of the URI is set.
+     *
      * @return bool
      */
     public function issetHostName()
@@ -101,12 +107,17 @@ class Request extends Message
         return isset($this->hostname);
     }
 
+    /**
+     * Unset the hostname portion of the URI.
+     */
     public function unsetHostname()
     {
         unset($this->hostname);
     }
 
     /**
+     * Return the method (e.g., GET, POST, PUT, DELETE)
+     *
      * @return string
      */
     public function getMethod()
@@ -115,6 +126,8 @@ class Request extends Message
     }
 
     /**
+     * Assign the method (e.g., GET, POST, PUT, DELETE)
+     *
      * @param string $method
      */
     public function setMethod($method)

src/pjdietz/WellRESTed/Response.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Response
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -8,13 +10,15 @@
 
 namespace pjdietz\WellRESTed;
 
+use \InvalidArgumentException;
+
 /**
  * A Response instance allows you to build an HTTP response and send it when
  * finished.
  *
- * @property string reasonPhrase  Text explanation of status code.
+ * @property string reasonPhrase Text explanation of status code.
- * @property int statusCode  HTTP status code
+ * @property int statusCode HTTP status code
- * @property-read string statusLine  HTTP status line, e.g. "HTTP/1.1 200 OK"
+ * @property-read string statusLine HTTP status line, e.g. "HTTP/1.1 200 OK"
  */
 class Response extends Message
 {
@@ -61,7 +65,7 @@ class Response extends Message
     }
 
     // -------------------------------------------------------------------------
-    // !Accessors
+    // Accessors
 
     /**
      * Provide a new entity body for the respone.
@@ -81,6 +85,8 @@ class Response extends Message
     }
 
     /**
+     * Return the portion of the status line explaining the status.
+     *
      * @return string
      */
     public function getReasonPhrase()
@@ -89,6 +95,8 @@ class Response extends Message
     }
 
     /**
+     * Assign an explaination for the status code. Not normally needed.
+     *
      * @param string $statusCodeMessage
      */
     public function setReasonPhrase($statusCodeMessage)
@@ -97,6 +105,8 @@ class Response extends Message
     }
 
     /**
+     * Return the status code.
+     *
      * @return int
      */
     public function getStatusCode()
@@ -105,9 +115,11 @@ class Response extends Message
     }
 
     /**
+     * Set the status code and optionally the reason phrase explaining it.
+     *
      * @param int $statusCode
      * @param string|null $reasonPhrase
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException
      */
     public function setStatusCode($statusCode, $reasonPhrase = null)
     {
@@ -239,7 +251,7 @@ class Response extends Message
             if (is_string($reasonPhrase)) {
                 $this->reasonPhrase = $reasonPhrase;
             } else {
-                throw new \InvalidArgumentException('$reasonPhrase must be a string (or null to use standard HTTP Reason-Phrase');
+                throw new InvalidArgumentException('$reasonPhrase must be a string (or null to use standard HTTP Reason-Phrase');
             }
 
         }

src/pjdietz/WellRESTed/Route.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRested\Route
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -8,24 +10,35 @@
 
 namespace pjdietz\WellRESTed;
 
+use \Exception;
+
 /**
  * A Route connects a URI pattern to a Handler.
- *
- * @package WellRESTed
  */
 class Route
 {
+    /**
+     * Regular expression matching URL friendly characters (i.e., letters,
+     * digits, hyphen and underscore)
+     */
     const RE_SLUG = '[0-9a-zA-Z\-_]+';
+
+    /** Regular expression matching digitis */
     const RE_NUM = '[0-9]+';
+
+    /** Regular expression matching letters */
     const RE_ALPHA = '[a-zA-Z]+';
+
+    /** Regular expression matching letters and digits */
     const RE_ALPHANUM = '[0-9a-zA-Z]+';
 
+    /** Regular expression matching a URI template variable (e.g., {id}) */
     const URI_TEMPLATE_EXPRESSION_RE = '/{([a-zA-Z]+)}/';
 
     /**
-     * Regular Expression to use to validate a template variable.
+     * Default regular expression used to match template variable
      *
-     * @var string
+     * @property string
      */
     static public $defaultVariablePattern = self::RE_SLUG;
 
@@ -61,7 +74,7 @@ class Route
      * @param string $uriTemplate
      * @param string $handler
      * @param array $variables
-     * @throws \Exception
+     * @throws Exception
      * @return Route
      */
     static public function newFromUriTemplate(
@@ -84,12 +97,7 @@ class Route
             $pattern .= '\/';
 
             // Is this part an expression or a literal?
-            if (preg_match(
+            if (preg_match(self::URI_TEMPLATE_EXPRESSION_RE, $part, $matches)) {
-                self::URI_TEMPLATE_EXPRESSION_RE,
-                $part,
-                $matches
-            )
-            ) {
 
                 // This part of the path is an expresion.
 
@@ -115,7 +123,7 @@ class Route
 
                 } else {
                     // Not sure why this would happen.
-                    throw new \Exception('Invalid URI Template.');
+                    throw new Exception('Invalid URI Template.');
                 }
 
             } else {

src/pjdietz/WellRESTed/Router.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * pjdietz\WellRESTed\Router
+ *
  * @author PJ Dietz <pj@pjdietz.com>
  * @copyright Copyright 2013 by PJ Dietz
  * @license MIT
@@ -18,6 +20,7 @@ class Router
 {
     /**
      * Array of Route objects
+     *
      * @var array
      */
     protected $routes;
@@ -41,6 +44,8 @@ class Router
     }
 
     /**
+     * Return the Response built by the Handler based on the Request
+     *
      * @param Request $request
      * @return Response
      */
@@ -68,6 +73,8 @@ class Router
     }
 
     /**
+     * Prepare a Resonse indicating a 404 Not Found error
+     *
      * @param Request $request
      * @return Response
      */