added doc blocks, edited documentation

Author: ctwillie

README.md

@@ -1,6 +1,6 @@
 # Laravel-Usps
 
-This package provides a very simple wrapper for the United States Postal Service API. Currently, this package only provides address verification features, but will soon comprise all features offered by the USPS API. In the meantime, consider using [johnpaulmedina/laravel-usps](https://github.com/johnpaulmedina/laravel-usps), which is a great package.
+This package provides a very simple wrapper for the United States Postal Service API. Currently, this package only provides address validation features, but will soon comprise all features offered by the USPS API. In the meantime, consider using [johnpaulmedina/laravel-usps](https://github.com/johnpaulmedina/laravel-usps), which is a great package.
 
 ### Prerequisites
 
@@ -42,7 +42,49 @@ In `config/services.php` add these three settings.
 ## Usage
 
 The current features offered by this package are listed below.
- - [Address Verification](#Address)
+ - [Address Validation](#Address)
+
+
+## Address Validation
+
+This `Address` class handles creating and formatting address data. Pass the constructor an associative array of address details. Array keys are case-sensitive.
+Below is an example of creating an address and making an api request for validation.
+
+```php
+use ctwillie\Usps\Address;
+
+$address = new Address([
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+]);
+
+$response = $address->validate();
+```
+The USPS api limits 5 address validations per request. If you need to validate more than one address at a time, pass a multi dim array to the `Address` constructor.
+
+```php
+use ctwillie\Usps\Address;
+
+$address1 = new Address([
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+]);
+
+$address2 = new Address([
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+]);
+
+$addresses = [$address1, $address2];
+
+$response = $addresses->validate();
+```
 
 ## Contributing
 

src/Usps/API.php

@@ -7,49 +7,75 @@
 use Spatie\ArrayToXml\ArrayToXml;
 use GuzzleHttp\Client;
 
+/**
+ * Class used by each entity to interact with the API and get configurations
+ * 
+ * Each entity will be responsible for managing its own data used in the api
+ * request. This class handles the common functions, such as, data formatting,
+ * creating http client, making request, returning response etc.
+ * 
+ */
 abstract class API {
 
     const PROD_URL = 'https://secure.shippingapis.com/ShippingAPI.dll';
     const LOCAL_URL = 'http://production.shippingapis.com/ShippingAPITest.dll';
     protected $env;
     protected $apiUrl;
     protected $userId;
+    protected $rootElements = [
+        'Verify' => 'AddressValidateRequest'
+    ];
 
+    /** Determines env to set api url, http client settings etc. */
     public function __construct() {
         $this->setEnvironment();
         $this->setUrl();
         $this->userId = config('services.usps.userid');
     }
 
-    // Determines the current application environment
+    /** Determines the current application env */
     public function setEnvironment()
     {
         if (Config::has('services.usps.env')) {
+
             $this->env = strtolower(config('services.usps.env'));
+
         } elseif (App::environment(['local', 'development'])) {
+
             $this->env = 'local';
-        } 
+        }
+
         $this->env = 'production';
     }
 
+    /** Determines the api url to use based on running env */
     public function setUrl()
     {
         $this->apiUrl = $this->env === 'local' ? self::LOCAL_URL : self::PROD_URL;
     }
 
+    /**
+     * Makes sure a userid has been provided
+     * 
+     * @throws Exception If no userid is found in config/services.php
+     */
     public function checkForUserId()
     {
         if (is_null($this->userId)) {
             throw new \Exception('USPS: A user ID is required. None found in config/services.php');
         }
     }
 
-    // create a map to determine the rootElementName foreach api type
+    /**
+     * Converts entity data into xml format and url encodes
+     * 
+     * @return string
+     */
     protected function convertToXML()
     {
         $xml = ArrayToXml::convert( $this->getRequestData(),
             [
-                'rootElementName' => $this->rootElementName,
+                'rootElementName' => $this->rootElements[$this->apiType],
 
                 '_attributes' => ['USERID' => $this->userId]
 
@@ -58,6 +84,14 @@ protected function convertToXML()
         return urlencode($xml);
     }
 
+    /**
+     * Handles making the api request
+     * 
+     * This method handles creating the http client and gathering
+     * all necessary data for making the api request.
+     * 
+     * @return StreamInterface of the response content body
+     */
     public function makeRequest()
     {
         $this->checkForUserId();
@@ -71,8 +105,12 @@ public function makeRequest()
         return $response->getBody();
     }
 
-    // Abstract to be defined by each entity
-    abstract public function getRequestData() : array;
+    /**
+     * Each entity decides the array structure for the request data
+     * 
+     * @return array
+     */
+    abstract public function getRequestData();
 
     public function validate()
     {

src/Usps/Address.php

@@ -2,11 +2,14 @@
 
 namespace ctwillie\Usps;
 
+/**
+ * This class gathers data for the 'Verify' api route
+ * 
+ * It is responsible for formatting address request data that
+ * will be handled by the API class
+ */
 class Address extends API
 {
-    // use map to determine root element
-    // key will be api type ('verify' => 'AddressValidateRequest')
-    protected $rootElementName = 'AddressValidateRequest';
     protected $apiType = 'Verify';
     protected $addresses = [];
     protected $allowedProperties = ['Address1','Address2','City','State','Zip4','Zip5'];
@@ -16,8 +19,6 @@ class Address extends API
      * Handles single or multiple addresses passes to constructor
      * 
      * @param array $addresses
-     * @return void
-     * 
      */
     public function __construct(array $addresses = [])
     {
@@ -26,11 +27,9 @@ public function __construct(array $addresses = [])
     }
 
     /**
-     * Handles multiple addresses 
+     * Handles adding multiple addresses 
      * 
      * @param array $addresses
-     * @return void
-     * 
      */
     public function handleMultipleAddresses(array $addresses)
     {
@@ -55,13 +54,9 @@ public function handleMultipleAddresses(array $addresses)
     }
 
     /**
-     * Handles single address 
+     * Handles adding a single address
      * 
      * @param array $address
-     * @return void
-     * 
-     * Add addAddress method which calls this method and checks five address limit
-     * 
      */
     public function handleSingleAddress(array $address)
     {
@@ -80,7 +75,12 @@ public function handleSingleAddress(array $address)
         }
     }
 
-    public function getRequestData() : array
+    /**
+     * Formats the request data.
+     * 
+     * @return array
+     */
+    public function getRequestData()
     {
         return ['Address' => $this->addresses];
     }